Skip to main content

​
Prerequisites

  • Node.js 24+ and npm
  • A local repository you want to index

​
Installation

Choose how you want to run SDL-MCP:

​
5-minute setup

1

Set config location

SDL-MCP stores its config and database in a global directory. Set the location before you begin, then open a new terminal:
# Windows — set once, persists across terminals
setx SDL_CONFIG_HOME "C:\[your path]"

# macOS / Linux — add to your shell profile
export SDL_CONFIG_HOME="$HOME/.sdl-mcp"
SDL_CONFIG_HOME tells SDL-MCP where to create sdlmcp.config.json. You can also use --config <path> on any command to point at a specific file.
2

Initialize and index

Run the one-line setup command. It creates your config, detects languages, indexes your codebase, and runs health checks:
sdl-mcp init -y --auto-index --config "C:\[same path as SDL_CONFIG_HOME]"
What this does:
  • Creates sdlmcp.config.json with sensible defaults
  • Detects the languages in your repo
  • Indexes all symbols into the graph database
  • Runs doctor checks to validate the setup
3

Start the MCP server

Start SDL-MCP in stdio mode so coding agents can connect:
sdl-mcp serve --stdio
If your environment has issues with file watching (e.g., Docker, WSL, or network drives), use --no-watch:
sdl-mcp serve --stdio --no-watch
4

Connect your agent

Point your MCP client at the SDL-MCP process. See Client setup for per-client config snippets.Your agent now has access to all 35 SDL-MCP tools.

​
First config example

The init command generates this config automatically. Here is what it looks like:
sdlmcp.config.json
{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": ".",
      "ignore": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
      "languages": ["ts", "tsx", "js", "jsx", "py", "go", "java", "cs", "c", "cpp", "php", "rs", "kt", "sh"],
      "maxFileBytes": 2000000
    }
  ],
  "graphDatabase": { "path": "./data/sdl-mcp-graph.lbug" },
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": true
  }
}

​
Optional: tool enforcement

Without enforcement, an agent can have SDL-MCP connected and still waste tokens on native read and shell tools. Tool enforcement makes agents use SDL-MCP exclusively. Generate an SDL-first setup for your client: 
sdl-mcp init --client claude-code --enforce-agent-tools
# other supported clients: codex, gemini, opencode
This enables SDL runtime and exclusive Code Mode, then generates repo-local instruction files and client-specific enforcement assets for the chosen client.

​
Optional: HTTP transport (multi-agent)

By default, sdl-mcp serve --stdio runs a single MCP session — one agent, one connection. Streamable HTTP mode exposes the same MCP tools over HTTP, enabling multiple agents to connect concurrently.
StdioStreamable HTTP
Connections1 agentUp to 8 concurrent agents (configurable)
SetupZero config — agent spawns the processStart server first, then point agents at the URL
Session isolationN/A (single session)Each connection gets its own MCP session
Reconnect supportNoneBuilt-in event store for resumable sessions
Graph UI + REST APINot availableAvailable at /ui/graph and /api/*
Best forSingle-agent workflows, simple setupsMulti-agent teams, shared dev servers, CI pipelines
Start the HTTP server: 
# Basic (localhost:3000)
sdl-mcp serve --http

# Custom host and port
sdl-mcp serve --http --host 0.0.0.0 --port 8080

# With explicit config
sdl-mcp serve --http --port 3000 --config "C:\sdl\global\sdlmcp.config.json"
On startup, the server prints a bearer token to stderr: 
[sdl-mcp] HTTP server listening on http://localhost:3000
[sdl-mcp] HTTP auth token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Agents must include this token as Authorization: Bearer <token> in every request. See Client setup for HTTP config snippets per client.

​
Verify the setup

After connecting your agent, verify it can call the four core tools:
  1. sdl.repo.register — register your codebase
  2. sdl.index.refresh — trigger indexing
  3. sdl.symbol.search — search for a symbol by name
  4. sdl.symbol.getCard — retrieve a Symbol Card
If those four calls succeed, you are ready for slice and code-window workflows.

​
Next steps

Client setup

Config snippets for Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode, and more.

Agent workflows

Copy the recommended AGENTS.md instructions to maximize token savings.

Configuration reference

Every config option with defaults and guidance.

MCP tools reference

Parameters and response shapes for all 35 MCP tools.

Build docs developers (and LLMs) love

Get started for freeTalk to us