Repository navigation
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>.
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>"}
}
}
}| 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.
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.
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 themA 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.
-
In an agent: list only the MCP tools it needs in its
allowed_tools, such asmcp__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./networkshows 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.
Start here
Guides
Reference