MCP — Model Context Protocol

MCP — the Model Context Protocol — is how Sonderr reaches beyond its built-in tools. An MCP server is a small program or HTTP endpoint that exposes tools the agent can call: your internal API, a database explorer, a company wiki, anything that speaks the protocol. This page covers configuring servers, the two transports, the security model that guards the boundary, and what a tool call is allowed to do.

1 · Why MCP exists here

Built-in tools cover the workspace: files, project checks, web research, Studios, email, wallet. Everything else — the tools specific to your stack — arrives as MCP servers. Sonderr treats them as first-class tools: once a server connects, its tools are discovered automatically, described to the model with proper schemas, and called like any native tool, subject to the same mode and access gates.

2 · Adding a server

Servers are configured in the runtime’s MCP config with a small, explicit set of fields: a name for the UI, then either a command (a local process) or a url (a remote endpoint). Local servers can take args and an env map; remote servers can reference a tokenEnv — the name of an environment variable holding an auth token, so the secret itself lives in the credential store, never in the config body. The transport is derived: a URL means HTTP, a command means stdio.

{ "name": "repo-tools", "command": "npx", "args": ["-y", "your-mcp-server"] }
{ "name": "docs-api",  "url": "https://mcp.internal.example.com/sse", "tokenEnv": "INTERNAL_MCP_TOKEN" }

3 · The two transports

stdio spawns the server as a child process and speaks JSON-RPC over pipes — the standard pattern for local tool servers. The runtime tracks whether the child is alive, restarts cleanly, and reserves its own environment variables so a server can’t see or spoil Sonderr’s runtime state. HTTP speaks to remote endpoints with pending-request matching by ID and timeouts, so a slow server can’t wedge the workspace. Either way, tools discovered from a connected server are listed, named and schema-checked before the model ever sees them.

4 · The security model

MCP is a door to the outside, so it gets the strictest framing in the product:

• HTTPS, DNS-pinned. Remote MCP requests connect only to addresses validated as public at resolution time — the pinning that prevents DNS rebinding between validation and connection. Redirects are rejected outright, and IPv6 transition and special-use ranges (the classic private-network escape hatches) are blocked.
• Secrets stay out of commands. Auth tokens are referenced by environment-variable name and injected at connect time; MCP secrets are never embedded in command arguments or environment values visible to other processes. Configuration and credentials are written owner-only, through exclusive no-follow temporary files, and symlinked paths are rejected.
• Re-checked, not assumed. Saved endpoints and subprocess environments are validated again at connection time — a config that was safe when written doesn’t get a free pass forever.
• Size-bounded responses. MCP response bodies and protocol frames are size-capped, so one chatty server can’t flood the context or the UI.

5 · What a tool call may do

Discovery is easy; mutation is guarded. Read-only MCP tools are usable where reads are allowed — Ask mode keeps its read-only built-ins, and remote reads still respect your access level. Mutating MCP tools require Build mode, an access level that permits them, and — the part that matters most — authorization from your present message: a tool call that was not included in the active request’s schema is refused, earlier context cannot authorize a current action, and a stale or negated instruction can’t be replayed as permission. The same rule that guards workspace edits guards every external tool, at the server execution boundary where guidance can’t be talked around.

6 · When a server misbehaves

Every server in the UI carries a connected flag, its transport, and a plain-language error string when something’s wrong — refused endpoint, dead child process, timeout, rejected token. Start there. Then the usual three: is the command runnable from your PATH (stdio), is the URL reachable without redirects (HTTP), and does the token env var actually resolve in the credential store. A server that connected fine yesterday and fails today usually means its own upstream changed — the error string will say which stage failed.