Configuration

SDL-MCP is configured via a single JSON file. This guide covers how to locate, create, and tune that file for your environment.

Config File Location

SDL-MCP resolves the config path in this order:

--config flag

Pass an explicit path on any command:

sdl-mcp serve --stdio --config "/path/to/sdlmcp.config.json"
sdl-mcp index --config "/path/to/sdlmcp.config.json"

SDL_CONFIG environment variable

Set once; all SDL-MCP commands pick it up:

# Linux / macOS
export SDL_CONFIG="/path/to/sdlmcp.config.json"

# Windows (persist across terminals)
setx SDL_CONFIG "C:\sdl\global\sdlmcp.config.json"

SDL_CONFIG_PATH is accepted as an alias.

SDL_CONFIG_HOME environment variable

Points SDL-MCP at a directory; the filename sdlmcp.config.json is appended automatically:

# Resolves to: C:\sdl\global\sdlmcp.config.json
setx SDL_CONFIG_HOME "C:\sdl\global"

OS default config directory

If none of the above are set, SDL-MCP writes and reads from the OS-standard user config directory.

Legacy local fallback

If no global config exists, SDL-MCP falls back to ./config/sdlmcp.config.json relative to the working directory.

Run sdl-mcp init -y --auto-index to create a config file interactively at the resolved location. You can also copy config/sdlmcp.config.example.json and edit it manually.

Minimal Required Config

Only two top-level fields are required — everything else has sensible defaults:

{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": "/workspace/my-repo"
    }
  ],
  "policy": {}
}

If graphDatabase.path is omitted, SDL-MCP defaults to <configDir>/sdl-mcp-graph.lbug.

Full Annotated Config Example

This is the complete example config shipped with SDL-MCP (config/sdlmcp.config.example.json) with all defaults shown:

{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": ".",
      "ignore": [
        "**/node_modules/**",
        "**/dist/**",
        "**/.next/**",
        "**/build/**",
        "**/.git/**",
        "**/coverage/**"
      ],
      "languages": ["ts", "tsx", "js", "jsx", "py", "go", "java", "cs", "c", "cpp", "php", "rs", "kt", "sh"],
      "maxFileBytes": 2000000,
      "includeNodeModulesTypes": true
    }
  ],
  "graphDatabase": {
    "path": "./data/sdl-mcp-graph.lbug"
  },
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": false,
    "defaultDenyRaw": true
  },
  "semantic": {
    "enabled": true,
    "provider": "local",
    "model": "all-MiniLM-L6-v2",
    "generateSummaries": false
  },
  "prefetch": {
    "enabled": true,
    "maxBudgetPercent": 20,
    "warmTopN": 50
  },
  "concurrency": {
    "maxSessions": 8
  },
  "httpAuth": {
    "enabled": false,
    "token": null
  },
  "indexing": {
    "engine": "rust",
    "concurrency": 8,
    "enableFileWatching": true
  }
}

Config Sections

repos[] — Repositories to index

Each entry registers a codebase for indexing. You can index multiple repos in a single config.

{
  "repos": [
    {
      "repoId": "my-repo",
      "rootPath": "/workspace/my-repo",
      "ignore": [
        "**/node_modules/**",
        "**/dist/**",
        "**/.next/**",
        "**/build/**",
        "**/.git/**",
        "**/coverage/**"
      ],
      "languages": ["ts", "tsx", "js", "jsx", "py", "go"],
      "maxFileBytes": 2000000,
      "includeNodeModulesTypes": true,
      "workspaceGlobs": null
    }
  ]
}

Field	Type	Default	Description
`repoId`	`string`	—	Required. Unique ID used in all MCP tool calls
`rootPath`	`string`	—	Required. Absolute or relative path to repo root
`ignore`	`string[]`	Common dirs	Glob patterns to exclude from indexing
`languages`	`string[]`	All supported	File extensions to index
`maxFileBytes`	`integer`	`2000000` (2 MB)	Files larger than this are skipped
`includeNodeModulesTypes`	`boolean`	`true`	Index `@types/*` for TypeScript call resolution
`workspaceGlobs`	`string[]`	`null`	Glob patterns for monorepo workspace `package.json` files
`packageJsonPath`	`string`	Auto	Override `package.json` location
`tsconfigPath`	`string`	Auto	Override `tsconfig.json` location

Supported languages: ts, tsx, js, jsx, py, go, java, cs, c, cpp, php, rs, kt, sh

Add "**/native/target/**" to ignore for Rust repos. Narrow languages to only what your repo uses for faster indexing. Set workspaceGlobs like ["packages/*/package.json"] for monorepos.

graphDatabase — Database file location

Controls where SDL-MCP stores the Ladybug graph database. Supports ${ENV_VAR} expansion.

{
  "graphDatabase": {
    "path": "./data/sdl-mcp-graph.lbug"
  }
}

If omitted, defaults to <configDir>/sdl-mcp-graph.lbug.

Field	Type	Default	Description
`path`	`string?`	`<configDir>/sdl-mcp-graph.lbug`	Path to the Ladybug database file

Use ${SDL_GRAPH_DB_PATH} for an environment-variable-driven path, or move to a fast SSD path if indexing is slow.

policy — Gated code access controls

Controls the proof-of-need gating system for raw code access via sdl.code.needWindow.

{
  "policy": {
    "maxWindowLines": 180,
    "maxWindowTokens": 1400,
    "requireIdentifiers": true,
    "allowBreakGlass": false,
    "defaultDenyRaw": true,
    "budgetCaps": null,
    "defaultMinCallConfidence": null
  }
}

Field	Type	Default	Description
`maxWindowLines`	`integer`	`180`	Max lines per raw code window (requests above this are clamped)
`maxWindowTokens`	`integer`	`1400`	Max tokens per raw code window (requests above this are clamped)
`requireIdentifiers`	`boolean`	`true`	Require non-empty `identifiersToFind` in `needWindow` calls
`allowBreakGlass`	`boolean`	`false`	Allow emergency override of policy denials (logged in audit trail)
`defaultDenyRaw`	`boolean`	`true`	Default deny for raw code — requires proof-of-need
`budgetCaps`	`object?`	`null`	Optional server-side budget defaults: `{ maxCards, maxEstimatedTokens }`
`defaultMinCallConfidence`	`number?`	`null`	Default threshold for call-edge filtering (0.0–1.0)

Requests exceeding maxWindowLines or maxWindowTokens are silently clamped, not rejected. Policy can be changed at runtime via sdl.policy.set.

Recommended CI config (tighter limits to control token spend):

{
  "policy": {
    "maxWindowLines": 120,
    "maxWindowTokens": 1000,
    "requireIdentifiers": true,
    "allowBreakGlass": false
  }
}

semantic — Embedding search and LLM summaries

Controls semantic search reranking, embedding generation, and LLM-powered symbol summaries.

{
  "semantic": {
    "enabled": true,
    "provider": "local",
    "model": "all-MiniLM-L6-v2",
    "generateSummaries": false,
    "summaryProvider": null,
    "summaryModel": null,
    "summaryApiKey": null,
    "summaryApiBaseUrl": null,
    "summaryMaxConcurrency": 5,
    "summaryBatchSize": 20
  }
}

Field	Type	Default	Description
`enabled`	`boolean`	`true`	Enable semantic reranking in symbol search
`provider`	`string`	`"local"`	Embedding provider: `"local"` (ONNX), `"api"`, or `"mock"`
`model`	`string`	`"all-MiniLM-L6-v2"`	Embedding model. Also supports `"nomic-embed-text-v1.5"`
`generateSummaries`	`boolean`	`false`	Generate LLM summaries during indexing
`summaryProvider`	`string?`	`null`	Summary LLM: `"api"` (Anthropic), `"local"` (OpenAI-compatible), `"mock"`
`summaryModel`	`string?`	`null`	LLM model for summaries (defaults per-provider)
`summaryApiKey`	`string?`	`null`	API key (falls back to `ANTHROPIC_API_KEY` env var)
`summaryApiBaseUrl`	`string?`	`null`	Base URL for OpenAI-compatible local providers
`summaryMaxConcurrency`	`integer`	`5`	Max concurrent LLM requests (1–20)
`summaryBatchSize`	`integer`	`20`	Symbols per LLM batch request (1–50)

See Semantic Setup for a full walkthrough of all providers.

prefetch — Predictive background warming

Enables background prefetch of likely-needed results during sdl-mcp serve.

{
  "prefetch": {
    "enabled": true,
    "maxBudgetPercent": 20,
    "warmTopN": 50
  }
}

Field	Type	Default	Range	Description
`enabled`	`boolean`	`true`	—	Toggle the prefetch queue
`maxBudgetPercent`	`integer`	`20`	1–100	Resource cap as % of configured budget
`warmTopN`	`integer`	`50`	min: 1	Symbols warmed on server startup

Prefetch metrics are available in sdl.repo.status under prefetchStats (queue depth, hit/waste rates, latency reduction).

Prefetch is disabled in CI and batch-only workflows. Enable it for long-running serve sessions.

concurrency — Session and tool limits

Controls concurrency for sessions, tool dispatch, and database connections. Primarily relevant in HTTP (multi-agent) mode.

{
  "concurrency": {
    "maxSessions": 8,
    "maxToolConcurrency": 8,
    "readPoolSize": 4,
    "writeQueueTimeoutMs": 30000,
    "toolQueueTimeoutMs": 30000
  }
}

Field	Type	Default	Range	Description
`maxSessions`	`integer`	`8`	1–16	Max concurrent HTTP sessions
`maxToolConcurrency`	`integer`	`8`	1–32	Max concurrent tool handler executions
`readPoolSize`	`integer`	`4`	1–8	LadybugDB read connection pool size
`writeQueueTimeoutMs`	`integer`	`30000`	1000–120000	Timeout for queued write operations (ms)
`toolQueueTimeoutMs`	`integer`	`30000`	5000–120000	Timeout for queued tool invocations (ms)

For multi-agent setups: Increase maxSessions up to 16. For resource-constrained systems: Lower maxToolConcurrency to 2–4.

httpAuth — Bearer-token auth for HTTP transport

Enables bearer-token authentication when running sdl-mcp serve --http. Has no effect on stdio transport.

{
  "httpAuth": {
    "enabled": false,
    "token": null
  }
}

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Enable auth (disabled by default)
`token`	`string?`	`null`	Static bearer token. When `null`, a random token is generated at startup

When token is null, the generated token is printed to stderr on startup:

[sdl-mcp] HTTP auth token: a1b2c3d4e5f6...

Set a fixed token for shared dev servers or CI pipelines:

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

Agents must include the token as Authorization: Bearer <token> in every request.

indexing — Engine and performance

Controls how and when source code is indexed.

{
  "indexing": {
    "engine": "rust",
    "concurrency": 8,
    "enableFileWatching": true,
    "maxWatchedFiles": 25000,
    "watchDebounceMs": 300
  }
}

Field	Type	Default	Range	Description
`engine`	`string`	`"rust"`	`"rust"` \| `"typescript"`	Indexer implementation
`concurrency`	`integer`	`8`	1–10	Concurrent file-processing workers
`enableFileWatching`	`boolean`	`true`	—	Auto-reindex on file changes
`maxWatchedFiles`	`integer`	`25000`	min: 1	Cap on tracked files
`watchDebounceMs`	`integer`	`300`	50–5000	Debounce delay for file watch events (ms)
`workerPoolSize`	`integer?`	Auto	1–16	Override worker pool thread count

Engine selection: The Rust engine is faster and is the default. If the native addon is unavailable (unsupported platform), SDL-MCP falls back to the TypeScript engine automatically. To force the TypeScript engine:

{
  "indexing": {
    "engine": "typescript"
  }
}

The TypeScript engine uses tree-sitter grammars for AST parsing and works everywhere Node.js runs with no native build requirements.CI/batch mode recommendations:

{
  "indexing": {
    "enableFileWatching": false,
    "concurrency": 2
  }
}

Get Started

Core Concepts

Guides

Support

Config File Location

Minimal Required Config

Full Annotated Config Example

Config Sections

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Support

​Config File Location

​Minimal Required Config

​Full Annotated Config Example

​Config Sections

Build docs developers (and LLMs) love

Config File Location

Minimal Required Config

Full Annotated Config Example

Config Sections