Skip to content

MCP Servers

SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

MCP Servers

The Model Context Protocol lets the harness use tools from separate programs and services: a file search, a database, an issue tracker. Each server's tools appear to the model as mcp__<server>__<tool>.

Where servers are configured

Servers are listed in mcp.json, in one of two places:

File For Notes
~/.config/venastine/mcp.json You, in every project Created empty at startup if it is missing, and the launch says where it is
.venastine/mcp.json in a project That project only Loaded only once you trust the project. /init --config creates an empty one

When the two name the same server, yours wins over the project's, because a project's file arrived with a repository you cloned.

The format is the one Claude Code uses, and keys the harness does not recognise are ignored, so a file shared with another client works as it is:

{
  "mcpServers": {
    "files": {
      "command": "npx",
      "args": ["-y", "@example/server"]
    },
    "tracker": {
      "url": "https://mcp.example.com/mcp",
      "headers": {"Authorization": "Bearer <your token>"}
    }
  }
}

Server entry fields

Field Transport Meaning
command, args stdio Start this local program
env, cwd stdio Extra environment variables, and the working directory
url HTTP or SSE The remote endpoint
type HTTP or SSE "sse" selects Server-Sent Events. A url without type is always streamable HTTP
headers HTTP or SSE Extra HTTP headers. Authorization is where a hosted server's credential usually goes
autoApprove (or auto_approve) both Skip the per-call approval for this server's tools. It must be a real JSON true; the string "false" warns and stays gated
disabled both Load nothing from this entry

A server that fails to connect is named and skipped. It never stops the harness.

What you are asked, and when

The first time a server of yours connects, you are asked once. You are shown the resolved command line or URL, whether it auto-approves, and the names of its environment variables and headers, never their values. The answer is tied to the entry's contents, so editing the entry later asks again. A project's servers are part of the project's trust prompt instead. Set VENASTINE_MCP_ACK_FULL=1 to see the raw JSON entry in that prompt, for an audit.

Then every call to an MCP tool asks, unless the server has "autoApprove": true. MCP tools are third-party code the model can reach, and config files gain entries that installers append, so the default is to ask.

MCP exposes no read-only or write labels, so the harness cannot tell a tool that searches from one that posts to a channel. The tool's own description, which the grant picker below shows you, is what you have to go on.

MCP tools in research runs

A research run has no one to ask for minutes at a time, so gated tools are hidden from it. MCP tools are the tools you can pre-grant for one run:

venastine --mode research --grant "query"                          # pick from a list
venastine --mode research --grant-tools mcp__files__search "query"  # name them

A grant covers that one run and is never saved. One budget of 150 granted calls (max_granted_tool_calls) is shared by all ten passes; past it, the run goes back to asking. See Tool Permissions.

Limiting what an MCP server can do

  • In an agent: list only the MCP tools it needs in its allowed_tools, such as mcp__files__search. See Writing Agents and Skills.
  • Network use: MCP servers reached over HTTP can be given their own ceiling on a metered connection, in config.yaml. /network shows the meters. Local stdio servers are not counted.
  • Output: anything key-shaped in a server's result is redacted before it reaches the model, however deeply it is nested in the server's JSON.

Checked against release 0.3.12 (commit f33ef8a). The README's MCP servers section is the reference.

Clone this wiki locally