Secrets and OAuth

SecretsCopy Anchor Link

Servers often need API keys in an environment variable, an argument or a header. Rather than writing them into config.json, store them as secrets: the configuration holds only a reference, secret://<name>, and the value lives in your operating system's keychain.

switchboard secret set github-token          # prompts for the value without echoing it
switchboard secret set github-token ghp_…    # or pass it directly
switchboard secret ls                        # names only
switchboard secret rm github-token

Secret names use letters, digits, ., - and _. The Secrets page in the web UI does the same; values are write-only there and cannot be read back.

"github": {
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "secret://github-token" }
}

A reference works anywhere in a stdio server's env or args, or in a remote server's headers, including inside a longer value:

"internal-api": {
  "transport": "http",
  "url": "https://mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer secret://internal-api-token" }
}

When the server starts, Switchboard reads each referenced value and passes it to the server. A missing secret stops the server from starting, with an error that names the secret, instead of starting it with an empty value. switchboard doctor also reports references to secrets that are not set.

Where the values are kept:

The keychain is used through the optional @napi-rs/keyring module. When it cannot be loaded or no keychain is available, values go to ~/.switchboard/secrets.json instead, readable only by your user (mode 600). switchboard status and switchboard secret ls say which one is in use.

OAuthCopy Anchor Link

Many remote MCP servers sign you in with OAuth instead of an API key. When such a server first starts and answers that sign-in is needed, its state becomes needs-auth and its tools are unavailable until you sign in:

switchboard server auth linear

1. Switchboard registers itself with the server's authorization server using dynamic client registration.
2. Your browser opens the sign-in page. The flow uses PKCE, and the redirect comes back to the daemon at http://127.0.0.1:<port>/oauth/callback, so the daemon must be running.
3. The client registration and tokens are stored in the secret store under oauth.<server>.*.

Tokens are refreshed automatically. switchboard server signout <name> forgets them. A server whose headers include an Authorization header never uses OAuth.

Clients never see these credentials: they talk to Switchboard, and Switchboard talks to the server.