Skip to content

client-setup.md

Latest commit

 

History

History
220 lines (163 loc) · 4.79 KB

client-setup.md

File metadata and controls

220 lines (163 loc) · 4.79 KB

Client Setup

Full setup instructions for each AI client. For the quick-start summary, see README.md.

Transport modes

Mode How it runs When to use
stdio (default) Process spawned by the client One AI client, simple setup
HTTP Long-lived server at http://127.0.0.1:3100/mcp Multiple clients sharing one server

Start the HTTP server:

npx -y codebase-context --http            # default port 3100
npx -y codebase-context --http --port 4000

Copy-pasteable templates: templates/mcp/stdio/.mcp.json and templates/mcp/http/.mcp.json.

Project routing contract

Automatic multi-project routing is evidence-backed only when the MCP host announces workspace roots. Treat that as the primary path.

If the host does not send roots, or still cannot tell which project is active, use one of the explicit fallbacks instead:

  • start the server with a single bootstrap path
  • set CODEBASE_ROOT
  • retry tool calls with project

If multiple projects are available and no active project can be inferred safely, the server returns selection_required instead of guessing.

Claude Code

claude mcp add codebase-context -- npx -y codebase-context

Claude Code only supports stdio. HTTP is not available for this client.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-context": {
      "command": "npx",
      "args": ["-y", "codebase-context"]
    }
  }
}

Claude Desktop only supports stdio.

Cursor

Stdio — add to .cursor/mcp.json in your project (copy from templates/mcp/stdio/.mcp.json):

{
  "mcpServers": {
    "codebase-context": {
      "command": "npx",
      "args": ["-y", "codebase-context"]
    }
  }
}

HTTP — start the server first, then add to .cursor/mcp.json (copy from templates/mcp/http/.mcp.json):

{
  "mcpServers": {
    "codebase-context": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

Windsurf

Open Settings > MCP and add (stdio only — HTTP is not documented for Windsurf yet):

{
  "mcpServers": {
    "codebase-context": {
      "command": "npx",
      "args": ["-y", "codebase-context"]
    }
  }
}

Codex

Stdio:

codex mcp add codebase-context npx -y codebase-context

HTTP — start the server first (npx -y codebase-context --http), then save a config file and pass it:

{
  "mcpServers": {
    "codebase-context": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}
codex --mcp-config /path/to/mcp-http.json

VS Code (Copilot)

Add .vscode/mcp.json to your project root. VS Code uses servers instead of mcpServers:

{
  "servers": {
    "codebase-context": {
      "command": "npx",
      "args": ["-y", "codebase-context"]
    }
  }
}

OpenCode

Add opencode.json to your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codebase-context": {
      "type": "local",
      "command": ["npx", "-y", "codebase-context"],
      "enabled": true
    }
  }
}

OpenCode also supports interactive setup via opencode mcp add.

Single-project fallback

If you only use one repo, append a project path:

codex mcp add codebase-context npx -y codebase-context "/path/to/your/project"

Or set an environment variable:

CODEBASE_ROOT=/path/to/your/project

Test a local build

Build the local branch first:

pnpm build

Then point your MCP client at the local build:

{
  "mcpServers": {
    "codebase-context": {
      "command": "node",
      "args": ["<path-to-local-build>/dist/index.js"]
    }
  }
}

If the default setup is not enough for your client, pass a project path explicitly:

{
  "mcpServers": {
    "codebase-context": {
      "command": "node",
      "args": ["<path-to-local-build>/dist/index.js", "/path/to/your/project"]
    }
  }
}

Check these three flows:

  1. Single project — call search_codebase or metadata. Routing is automatic.

  2. Multiple projects on a roots-capable host — open two repos or a monorepo. Call codebase://context. Expected: workspace overview, then automatic routing once a project is active.

  3. Ambiguous or no-roots selection — start without a bootstrap path, call search_codebase. Expected: selection_required. Retry with project set to apps/dashboard or /repos/customer-portal.

For monorepos, test all three selector forms:

  • relative subproject path: apps/dashboard
  • repo path: /repos/customer-portal
  • file path: /repos/monorepo/apps/dashboard/src/auth/guard.ts