Client setup

SDL-MCP supports any MCP-compatible client. Use the tabs below to find the right config for your agent.

Compatible clients

Client	Supported transports	Quick setup
Claude Code	stdio, HTTP	`sdl-mcp init --client claude-code`
Claude Desktop	stdio	`sdl-mcp init --client claude-code`
Cursor	stdio, HTTP	Standard MCP server config
Windsurf	stdio, HTTP	Standard MCP server config
Codex CLI	stdio	`sdl-mcp init --client codex`
Gemini CLI	stdio, HTTP	`sdl-mcp init --client gemini`
OpenCode	stdio, HTTP	`sdl-mcp init --client opencode`
Any MCP client	stdio / HTTP	`sdl-mcp serve --stdio` or `--http`

Stdio configs

With stdio transport, the agent spawns the SDL-MCP process directly. No separate server process is needed.

Add to your Claude Code MCP config (.claude/settings.json or the global Claude config):

.claude/settings.json

"sdl-mcp": {
  "type": "stdio",
  "command": "C:\\nvm4w\\nodejs\\sdl-mcp.cmd",
  "args": [
    "serve",
    "--stdio"
  ],
  "env": {
    "SDL_CONFIG": "[path-to-global]/sdlmcp.config.json"
  }
}

serve --stdio is required — running sdl-mcp alone does not start the MCP server.

If you installed SDL-MCP globally (not via NVM), replace the command path with the result of which sdl-mcp (macOS/Linux) or where sdl-mcp (Windows).

Claude Desktop uses the same config format as Claude Code. Add to your Claude Desktop MCP settings:

"sdl-mcp": {
  "type": "stdio",
  "command": "sdl-mcp",
  "args": [
    "serve",
    "--stdio"
  ],
  "env": {
    "SDL_CONFIG": "[path-to-global]/sdlmcp.config.json"
  }
}

Add to your Cursor MCP config (.cursor/mcp.json or global Cursor settings):

.cursor/mcp.json

{
  "mcpServers": {
    "sdl-mcp": {
      "command": "sdl-mcp",
      "args": [
        "serve",
        "--stdio"
      ],
      "env": {
        "SDL_CONFIG": "[path-to-global]/sdlmcp.config.json"
      }
    }
  }
}

Windsurf uses the same MCP server format as Cursor. Add to your Windsurf MCP config:

{
  "mcpServers": {
    "sdl-mcp": {
      "command": "sdl-mcp",
      "args": [
        "serve",
        "--stdio"
      ],
      "env": {
        "SDL_CONFIG": "[path-to-global]/sdlmcp.config.json"
      }
    }
  }
}

Codex CLI uses a TOML config file:

codex-config.toml

[mcp_servers.sdl-mcp]
command = "npx"
args = [
  "--yes",
  "sdl-mcp@latest",
  "serve",
  "--stdio",
  "--config",
  "[path-to-global]/sdlmcp.config.json",
]

[mcp_servers.sdl-mcp.env]
SDL_CONFIG = "[path-to-global]/sdlmcp.config.json"

Run sdl-mcp init --client codex to generate this file automatically.

Add to your Gemini CLI MCP config:

"sdl-mcp": {
  "type": "stdio",
  "command": "C:\\nvm4w\\nodejs\\sdl-mcp.cmd",
  "args": [
    "serve",
    "--stdio"
  ],
  "env": {
    "SDL_CONFIG": "[path-to-global]/sdlmcp.config.json"
  }
}

Run sdl-mcp init --client gemini to generate the recommended config and instruction files automatically.

Add to your OpenCode MCP config:

"sdl-mcp": {
  "type": "local",
  "command": [
    "C:\\nvm4w\\nodejs\\sdl-mcp.cmd",
    "-c",
    "[path-to-global]\\sdlmcp.config.json",
    "serve",
    "--stdio"
  ],
  "enabled": true
}

Run sdl-mcp init --client opencode to generate the recommended config and instruction files automatically.

HTTP transport configs

HTTP (Streamable HTTP) transport lets multiple agents connect to one running SDL-MCP server concurrently. Start the server first:

sdl-mcp serve --http --port 3000

The server prints a bearer token on startup. Copy it — you’ll need it in every agent config:

[sdl-mcp] HTTP server listening on http://localhost:3000
[sdl-mcp] HTTP auth token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Claude Code
Cursor / generic MCP client
Legacy SSE

.claude/settings.json

"sdl-mcp": {
  "type": "streamableHttp",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer <token-from-server-startup>"
  }
}

{
  "mcpServers": {
    "sdl-mcp": {
      "transport": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-server-startup>"
      }
    }
  }
}

For older MCP clients that do not support Streamable HTTP:

{
  "mcpServers": {
    "sdl-mcp": {
      "transport": "sse",
      "url": "http://localhost:3000/sse",
      "headers": {
        "Authorization": "Bearer <token-from-server-startup>"
      }
    }
  }
}

The SSE transport (/sse) is deprecated. Use Streamable HTTP (/mcp) if your client supports it.

HTTP server endpoints

Endpoint	Method	Purpose
`/mcp`	POST	Streamable HTTP MCP calls (primary)
`/mcp`	GET	Server-sent events for push notifications
`/mcp`	DELETE	Terminate an MCP session
`/sse`	GET	Legacy SSE transport (deprecated)
`/message`	POST	Legacy SSE message endpoint (deprecated)
`/health`	GET	Health check (no auth required)
`/ui/graph`	GET	Interactive graph explorer
`/api/*`	GET	REST API for graph queries

Static auth token

By default, SDL-MCP generates a random bearer token on each server start. To use a fixed token across restarts, set it in your config:

sdlmcp.config.json

{
  "httpAuth": {
    "enabled": true,
    "token": "my-static-token"
  }
}

Set "enabled": false to disable auth entirely for trusted local environments.

Tool enforcement

Without enforcement, an agent can have SDL-MCP connected and still use native read and shell tools, bypassing the token savings. Tool enforcement makes your agent prefer SDL-MCP tools exclusively. Run the init command with your client and --enforce-agent-tools:

sdl-mcp init --client claude-code --enforce-agent-tools
# other supported clients: codex, gemini, opencode

This generates:

Repo-local instruction files (e.g., CLAUDE.md, AGENTS.md) with SDL-first workflow rules
Client-specific enforcement assets (tool allowlists, Code Mode config)

Tool enforcement is optional but strongly recommended. Without it, agents may still read files directly, wasting tokens that SDL-MCP would otherwise save.

VSCode extension

The sdl-mcp-vscode extension provides live buffer integration: as you type in VS Code, unsaved editor changes are pushed to SDL-MCP’s in-memory overlay store and become immediately queryable by connected agents — no manual save or re-index needed. Install the extension from the sdl-mcp-vscode/ directory in the repository. See the extension README for setup instructions.

Verification

After connecting any client, verify the integration with these four MCP tool calls:

sdl.repo.register — register your codebase
sdl.index.refresh — trigger indexing
sdl.symbol.search — search for a symbol by name
sdl.symbol.getCard — retrieve a Symbol Card

If those four calls succeed, your client is correctly connected and ready for slice and code-window workflows.

Get Started

Core Concepts

Guides

Support

Compatible clients

Stdio configs

HTTP transport configs

HTTP server endpoints

Static auth token

Tool enforcement

VSCode extension

Verification

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Support

​Compatible clients

​Stdio configs

​HTTP transport configs

​HTTP server endpoints

​Static auth token

​Tool enforcement

​VSCode extension

​Verification

Build docs developers (and LLMs) love

Compatible clients

Stdio configs

HTTP transport configs

HTTP server endpoints

Static auth token

Tool enforcement

VSCode extension

Verification