Configuration
The format of ~/.switchboard/config.json.
Switchboard keeps its configuration in ~/.switchboard/config.json (under SWITCHBOARD_HOME if set). The web UI and the CLI edit this file for you; you can also edit it by hand. The running daemon reloads it when it changes and tells connected clients if their tools changed. An invalid edit is reported in the daemon's log and ignored, and the last valid configuration stays in use.
{
"version": 1,
"servers": {
"github": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "secret://github-token" },
"idleTimeoutSec": 600
},
"linear": {
"transport": "http",
"url": "https://mcp.linear.app/mcp"
}
},
"profiles": {
"work": {
"servers": ["github", "linear"],
"exclude": ["github.delete_repository"],
"surface": "auto",
"autoThreshold": 40
},
"personal": {
"servers": ["github"],
"surface": "code",
"budgets": { "timeoutMs": 30000, "maxToolCalls": 64 }
}
},
"clientRules": [
{ "client": "cursor*", "profile": "work" },
{ "client": "claude-code", "profile": "personal" }
],
"defaultProfile": "personal"
}Server and profile names are the keys of servers and profiles. They are used in tool names and URLs, so they must be 1 to 48 characters of lowercase letters, digits, - and _, starting with a letter or digit.
servers
Each server is an MCP server Switchboard can start or connect to.
| Field | Type | Description |
|---|---|---|
transport | "stdio" | "http" | "sse" | how to reach the server. http tries Streamable HTTP and falls back to SSE; sse uses SSE only |
command | string | stdio: the program to run |
args | string[] | stdio: its arguments; may contain secret:// references |
env | object | stdio: extra environment variables, added to the daemon's own; values may contain secret:// references |
cwd | string | stdio: the working directory |
url | string | http, sse: the server's endpoint |
headers | object | http, sse: request headers; values may contain secret:// references |
description | string | a note for yourself |
enabled | boolean | false hides the server's tools from every profile. Default true |
idleTimeoutSec | number | stop the server after this many seconds without a call; 0 keeps it running. Default 600 |
callTimeoutSec | number | time limit for a single tool call. Default 120 |
profiles
| Field | Type | Description |
|---|---|---|
description | string | shown in the web UI, and sent to clients as part of the session's instructions |
servers | string[] | servers whose tools are all included |
include | string[] | extra tools, as server.tool or server.*; * is a wildcard in either part |
exclude | string[] | tools to remove, same patterns; applied last |
overrides | object | per-tool changes keyed by server.tool: { "name": "...", "description": "..." } |
surface | "auto" | "passthrough" | "meta" | "code" | how tools are presented. Default "auto" |
autoThreshold | number | with auto, the most tools served as passthrough. Default 40 |
budgets.timeoutMs | number | code mode: time limit per run. Default 30000 |
budgets.maxToolCalls | number | code mode: tool calls per run. Default 64 |
budgets.memoryMb | number | code mode: sandbox memory. Default 64 |
budgets.maxSourceBytes | number | code mode: size of the code. Default 65536 |
budgets.maxResultChars | number | code mode: result size before truncation. Default 24000 |
Every server listed in servers must exist. See Profiles, Tool surfaces and Code mode.
clientRules
Rules that pick a profile from the MCP client's name, when the URL and headers do not. They are tried in order and the first match wins.
| Field | Type | Description |
|---|---|---|
client | string | a case-insensitive glob matched against the client's clientInfo.name, as in cursor* |
profile | string | the profile to use; it must exist |
See Profile resolution.
defaultProfile
The profile for connections that nothing else assigns; it must exist. Without one, such connections are refused.
Other files
See Where Switchboard keeps its files for the other files in ~/.switchboard.