MCP
User mcp.json plus workspace .spirit/mcp.json. Workspace wins on the same server name.
MCP servers add tools, resources, and prompts from outside Spirit.
| Scope | Path |
|---|---|
| User | {spiritDataDir}/mcp.json |
| Workspace | {workspace}/.spirit/mcp.json |
When both files define the same server name, the workspace entry wins.
Manage servers in Settings → MCPs, or with spirit mcp in the CLI (list, show, init, enable, disable, inspect, tools, call-tool, …). MCP servers bundled in an extension run when that extension is enabled. They do not appear in this settings list.
MCP tools merge into the same tool list the agent already has. They still go through approval when they are high-risk.
File fields
The root object has only servers. Each server must include transport, with type set to stdio or http.
| Field | Description |
|---|---|
servers | Object. Keys are server names |
displayName | Optional. UI label; defaults to the server name. display_name is also accepted |
enabled | Optional. Defaults to true |
capabilities.tools | Optional. Defaults to true |
capabilities.resources | Optional. Defaults to true |
capabilities.prompts | Optional. Defaults to true |
transport.type | Required. stdio or http |
stdio
| Field | Description |
|---|---|
command | Required. Launch command |
args | Optional. Command arguments |
env | Optional. Environment variables. Values may use ${env:NAME} |
cwd | Optional. Working directory |
timeoutMs | Optional. Timeout in milliseconds. timeout_ms is also accepted |
stderr | Optional. inherit (default) or pipe |
http
| Field | Description |
|---|---|
url | Required. Server URL |
headers | Optional. Request headers. Values may use ${env:NAME} |
timeoutMs | Optional. Timeout in milliseconds. timeout_ms is also accepted |
Extension secret references
HTTP headers bundled by an extension may reference secrets declared in that extension's manifest.secretSlots. This syntax is not available in user or workspace mcp.json files.
${extension-secret:SLOT}inserts the complete secret value.${extension-secret:SLOT:FIELD}parses the secret as a JSON object and inserts a top-level non-empty string field.
For example, an extension storing { "accessToken": "...", "login": "..." } in its oauthCredentials slot can use Bearer ${extension-secret:oauthCredentials:accessToken} as its Authorization header. The host resolves the reference when refreshing MCP configuration, never writes the resolved value to mcp.json, and refreshes the tools catalog when extension secrets change. A missing or invalid secret skips only the affected server.
Example
{
"servers": {
"local-docs": {
"displayName": "Local docs",
"enabled": true,
"capabilities": {
"tools": true,
"resources": true,
"prompts": false
},
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "example-mcp-server"],
"env": {
"API_TOKEN": "${env:EXAMPLE_API_TOKEN}"
},
"cwd": "/path/to/workspace",
"timeoutMs": 15000,
"stderr": "pipe"
}
},
"remote-tools": {
"transport": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:EXAMPLE_MCP_TOKEN}"
},
"timeoutMs": 20000
}
}
}
}