Spirit
Download

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.

ScopePath
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.

FieldDescription
serversObject. Keys are server names
displayNameOptional. UI label; defaults to the server name. display_name is also accepted
enabledOptional. Defaults to true
capabilities.toolsOptional. Defaults to true
capabilities.resourcesOptional. Defaults to true
capabilities.promptsOptional. Defaults to true
transport.typeRequired. stdio or http

stdio

FieldDescription
commandRequired. Launch command
argsOptional. Command arguments
envOptional. Environment variables. Values may use ${env:NAME}
cwdOptional. Working directory
timeoutMsOptional. Timeout in milliseconds. timeout_ms is also accepted
stderrOptional. inherit (default) or pipe

http

FieldDescription
urlRequired. Server URL
headersOptional. Request headers. Values may use ${env:NAME}
timeoutMsOptional. 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
      }
    }
  }
}