MCP Servers

SideCar supports the Model Context Protocol (MCP) for connecting to external tools and data sources.

What is MCP?

MCP is an open protocol that lets AI assistants call external tools — databases, APIs, file systems, and custom scripts. MCP tools appear alongside SideCar’s built-in tools and go through the same approval flow.

Transport types

SideCar supports three transport types:

Transport	Use case	Configuration
stdio (default)	Local processes on your machine	`command` + `args`
http	Remote servers via Streamable HTTP	`url`
sse	Remote servers via Server-Sent Events	`url`

Configuration

VS Code settings

Add MCP servers via the sidecar.mcpServers setting:

"sidecar.mcpServers": {
  "server-name": {
    "type": "stdio",
    "command": "executable",
    "args": ["arg1", "arg2"],
    "env": { "API_KEY": "your-key" }
  }
}

The type field defaults to "stdio" and can be omitted for local servers.

`.mcp.json` project file

For team-shared configurations, create a .mcp.json file at your workspace root. This format is compatible with Claude Code’s project-scope config:

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    "local-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    }
  }
}

Merge behavior: VS Code settings take precedence over .mcp.json. If both define a server with the same name, the VS Code setting wins. This lets individuals override shared project configs.

Environment variable expansion: Use ${VAR_NAME} in env values and HTTP headers. Variables resolve from process.env merged with the server’s env config. This keeps secrets out of version control.

Transport examples

stdio (local process)

"sidecar.mcpServers": {
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
  }
}

HTTP (remote server)

"sidecar.mcpServers": {
  "production-api": {
    "type": "http",
    "url": "https://mcp.mycompany.com/api",
    "headers": {
      "Authorization": "Bearer ${MCP_TOKEN}"
    }
  }
}

SSE (Server-Sent Events)

"sidecar.mcpServers": {
  "streaming-server": {
    "type": "sse",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "X-API-Key": "${SSE_API_KEY}"
    }
  }
}

Common server examples

Filesystem

Give SideCar access to files outside your workspace:

"sidecar.mcpServers": {
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
  }
}

SQLite database

Query a local database:

"sidecar.mcpServers": {
  "sqlite": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
  }
}

GitHub

Access GitHub repos, issues, and PRs:

"sidecar.mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "your-token"
    }
  }
}

Per-tool configuration

Disable specific tools from a server using the tools config:

"sidecar.mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "your-token" },
    "tools": {
      "delete_repository": { "enabled": false },
      "delete_branch": { "enabled": false }
    }
  }
}

Disabled tools are filtered out during discovery and never appear in the agent’s tool list.

Output size limits

Large MCP tool results can consume excessive context. Control this with maxResultChars:

"sidecar.mcpServers": {
  "database": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "large.db"],
    "maxResultChars": 20000
  }
}

The default limit is 50,000 characters. Results exceeding the limit are truncated with a message indicating the total size.

Lazy tool schemas

MCP tool schemas load lazily by default: the prompt catalog carries a compact one-line stub per tool (name + first sentence + a describe_tool pointer) instead of the full input schema. The model calls describe_tool('mcp_<server>_<tool>') to fetch the real parameter list before first use. This substantially cuts the fixed context cost of connected MCP servers — which matters most on small local models.

Dispatch is unaffected: tool calls always resolve against the full schema and executor, and the schema is never re-sent once fetched.

For servers whose tools are used on nearly every run, skip the extra describe_tool round-trip by injecting their full schemas upfront with alwaysLoad:

"sidecar.mcpServers": {
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
    "alwaysLoad": true
  }
}

Mutation discipline (write verification)

MCP writes are fire-and-trust by default: the tool returns success, but nothing confirms the fields actually landed on the external system (partial writes, silently dropped fields, server-side transformations). SideCar extends its “evidence, not exit codes” completion-gate discipline to MCP:

Tools the server annotates readOnlyHint: true (MCP ToolAnnotations) are reads. For unannotated tools (many popular servers ship no annotations), a conservative read-verb name heuristic applies (get_*, list_*, search_*, …); anything unrecognized is treated as a mutation.
A successful mutation stays unverified until a later successful read-only call to the same server.
If the agent tries to finish with unverified mutations, the completion gate injects one bounded reprompt: read the resource back, compare every field you set, and on any mismatch report it and leave the resource in a draft/unpublished state instead of claiming success.

This is a reliability discipline, not a security boundary — the read-back comes from the same server, so it verifies transport and semantics, not server honesty. The security controls are the approval flow (cautious/manual modes prompt per call; autonomous audit-logs instead — see How MCP tools work) and workspace trust. Rides sidecar.completionGate.enabled.

Server status

Use the /mcp slash command to check the status of all connected servers:

/mcp

This shows each server’s name, connection status, transport type, tool count, uptime, and any errors.

Health monitoring

SideCar monitors MCP server health automatically:

Connection failures are reported with specific error messages
Automatic reconnection uses exponential backoff (2s, 5s, 15s)
Settings changes trigger automatic reconnection to all servers
Workspace trust — MCP servers from workspace settings or .mcp.json trigger a trust prompt before connecting (since they can spawn processes)

How MCP tools work

MCP tools are discovered automatically when the server starts
They appear in the agent’s tool list with an mcp_<server>_<tool> prefix
Descriptions are prefixed with [MCP: <server>] for clarity
Schemas load lazily by default — the catalog carries one-line stubs and the model fetches full schemas via describe_tool (see Lazy tool schemas)
Tool calls go through the same approval flow (cautious/autonomous/manual/review)
Tool permissions (sidecar.toolPermissions) apply to MCP tools by their prefixed name
MCP tools require approval in cautious and manual modes. In autonomous mode they execute without a prompt (that is the mode’s contract) and every call is audit-logged ([AUTONOMOUS] line + .sidecar/logs/mcp.jsonl); force a per-call prompt for specific tools with sidecar.toolPermissions: { "mcp_<server>_<tool>": "ask" }

Building MCP servers

SideCar includes a built-in /mcp-builder skill that guides you through creating high-quality MCP servers. It covers:

TypeScript and Python implementation patterns
Tool schema design with Zod/Pydantic
Error handling and pagination
Transport setup (stdio and HTTP)
Testing with MCP Inspector
Evaluation question generation

Type /mcp-builder in chat to start, or describe the API you want to wrap.

Full configuration reference

Field	Type	Default	Description
`type`	`"stdio"` \| `"http"` \| `"sse"`	`"stdio"`	Transport type
`command`	string	—	Executable to spawn (stdio)
`args`	string[]	`[]`	Command arguments (stdio)
`env`	object	`{}`	Environment variables (stdio) or variable source for header expansion
`url`	string	—	Server URL (http/sse)
`headers`	object	`{}`	HTTP headers (http/sse). Supports `${VAR}` expansion
`tools`	object	`{}`	Per-tool config: `{ "tool_name": { "enabled": false } }`
`toolAllowlist`	string[]	—	When set, only listed tools are registered; all others are silently dropped
`maxResultChars`	number	`50000`	Maximum result size in characters before truncation
`alwaysLoad`	boolean	`false`	Inject full tool schemas into the prompt upfront instead of lazy one-line stubs

Troubleshooting

Check server status: run /mcp in chat to see connection status and errors
Verify installation: run the MCP server command manually in your terminal
Check logs: open the “SideCar Agent” output channel for connection errors
PATH issues: ensure npx and node are in your PATH if using npx-based servers
Windows: when using npx on Windows, you may need to wrap with cmd /c npx
HTTP servers: ensure the URL is reachable and returns valid MCP responses
Trust prompts: if servers from .mcp.json don’t connect, check if you blocked the workspace trust prompt

MCP Servers

MCP Servers

What is MCP?

Transport types

Configuration

VS Code settings

.mcp.json project file

Transport examples

stdio (local process)

HTTP (remote server)

SSE (Server-Sent Events)

Common server examples

Filesystem

SQLite database

GitHub

Per-tool configuration

Output size limits

Lazy tool schemas

Mutation discipline (write verification)

Server status

Health monitoring

How MCP tools work

Building MCP servers

Full configuration reference

Troubleshooting

`.mcp.json` project file