MCP Connections
Give your agents more than the codebase. MCP Connections let you wire external tool servers — up-to-date library docs, web search, product analytics, error monitoring, or any server you choose — into every workspace, so the agents in your panes can call them. Set a connector up once and Koda makes it available to the CLIs automatically.
Overview
Open Settings → MCP (the gear in the header, or the command palette). You'll see a grid of built-in connectors plus a Custom tile, and a list of the connections you've set up. As the panel puts it: connect external tools your agents can call — enabled connectors are wired into every workspace's agent CLI automatically.
A connection is global: configure it once and it applies to every workspace you open, so you're not re-entering keys per project.
Built-in connectors
Koda ships a curated catalog covering the tools agents reach for most. Pick one and Koda knows its endpoint and which key it needs.
| Connector | Category | What it gives an agent | Auth |
|---|---|---|---|
| Context7 | Docs | Up-to-date library docs & code examples, in-context. | API key (optional — keyless works, rate-limited) |
| Exa | Search | AI-native web search with full-content retrieval. | API key |
| PostHog | Analytics | Product analytics, funnels & feature flags. | Personal API key |
| Sentry | Observability | Error & performance monitoring, with Seer fixes. | OAuth (the CLI runs the handshake on first use) |
| + Custom | Custom | Any MCP server you supply, by URL. | Optional auth header |
Each named connector links to its provider's docs from the form, so getting a key is one click away.
Custom servers
The Custom MCP tile connects any MCP server by URL — http or sse transport. Give it a label, the server URL, and (optionally) an auth header name; the header's value is stored in the vault like any other secret. The URL is validated to be http(s) before it's saved.
How your keys are handled
This is where Koda's locked architecture — real CLIs, no token proxy — shapes the design. Koda never becomes an MCP client for these servers and never sends your key anywhere. It only writes the config your own agent CLIs read, and hands the secret to the CLI the same way you would.
- Stored in the vault. Keys are encrypted by your OS keychain (
safeStorage), bound to your user, and decrypted only inside Koda's main process — never echoed back to the interface. - Referenced, never written in plaintext. The config that registers a server refers to the key as an environment variable (
${VAR}). The plaintext value is never written to a config file on disk. - Injected at spawn. When a pane starts, Koda injects the decrypted key into that pane's environment, so the CLI resolves
${VAR}itself. The secret lives in process memory for that pane, not in a file.
Enabling, testing & status
Every connection in the list shows a status dot and a one-word state:
| State | Meaning |
|---|---|
| Active | Enabled and has the key it needs — wired into your workspaces. |
| Needs key | Enabled but missing a required key. Add the key to activate it. |
| Disabled | Turned off — left out of the config until you re-enable it. |
- Enable per connection — a toggle controls whether a connection is wired into your workspaces, so you can keep a server configured but dormant.
- Test — a Test button checks a connection so you can confirm it's reachable before relying on it.
- Add another — set up more than one connection to the same provider (for example, two PostHog projects).
How it's wired
Enabled connections are merged into the mcpServers configuration your agent CLIs read, keyed by connection. The merge preserves anything already there — including Koda's own coordination server and any servers you configured by hand. Each entry points the CLI at the connector's endpoint and references its key by env-var name, which Koda supplies at pane spawn.
Because the wiring is just config the CLIs already understand, connections work across the agents Koda supports — the agent calls the tool, Koda stays out of the way.