Skip to content
Docs menu

MCP servers

Give the agent tools from MCP servers in Claude Code's .mcp.json format, and use your organisation's approved servers with sign-in and tool pins.

View .md

venom reads MCP servers from the same files as Claude Code and runs them with pi's MCP client. An organisation can also approve a set of servers centrally; each member then turns them on or off and signs in.

Quick start

// .mcp.json in the project (or ~/.claude.json for yourself)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "docs": { "type": "http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } }
  }
}

Start venom in the project and trust it when asked: project servers run code from the repository, so they start only after trust.

Where servers come from

Scope File Notes
local ~/.claude.json, projects[<cwd>] wins over project and user
project .mcp.json needs project trust; an untrusted one never replaces a user or local server of the same name
user ~/.claude.json
plugin a plugin's .mcp.json or mcpServers ${CLAUDE_PLUGIN_ROOT} / ${VENOM_PLUGIN_ROOT} expand
org the org policy's approved servers below

disabledMcpjsonServers in any Claude settings file skips those project servers. With --offline, remote (http, sse) servers are registered disabled; stdio servers still run.

Server entries

Field What
command, args, env, cwd a stdio server
type: "http" or "streamable-http", url, headers a streamable-HTTP server
type: "sse", url, headers a legacy HTTP+SSE server, run through venom's stdio bridge (venom sets VENOM_MCP_SSE_URL and VENOM_MCP_SSE_HEADERS, a JSON object of headers, on the bridge process; you do not set them)
timeout milliseconds
oauth clientId, callbackPort, authServerMetadataUrl, scopes
alwaysLoad true loads the tools up front; by default they are deferred behind tool_search, as in Claude Code
exposure, toolExposure pi's own exposure settings, passed through

${VAR} and ${VAR:-default} expand in command, args, env, url and headers. Credential variables (OPENAI_API_KEY, VENOM_API_KEY, AWS_*, NPM_TOKEN, proxies) read as empty in a remote server's url and headers, and venom's own control-plane credentials never reach any server. {{secret:NAME}} in env and headers reads from venom's secrets vault. Not supported: headersHelper and type: "ws" (a diagnostic says so).

Every MCP tool call goes through venom's permission gate like any tool; rules name tools as mcp__<server>__<tool>.

Your organisation's servers

With Venom Cloud, the signed org policy can carry a registry of approved servers (venom cloud login or venom policy sync installs it). The policy turns some on by default; your choice lives in your home config.

venom mcp list                 # each approved server: on or off and why, auth, its tool pin
venom mcp enable linear        # mcp.enabled in ~/.venom/config.yaml
venom mcp disable sentry       # mcp.disabled, also for one the policy turns on
venom mcp connect              # browser sign-in for each enabled OAuth server without a token
venom mcp connect linear --force
Command What
venom mcp list [--json] approved servers, enabled or not, signed in or not, pin status
venom mcp enable <name>, venom mcp disable <name> write mcp.enabled / mcp.disabled
venom mcp connect [<name>…] [--force] sign in, one server after another; --force signs in again. In a session: /mcp-connect [<name>…] [--force]
venom mcp pin <name> connect and print the tools hash, for the admin's tools_sha256
venom mcp diff <name> the pinned tool descriptions against the server's current ones (exit 1 when they differ)
venom mcp approve <name> accept the current descriptions as your pin (refused when the policy pins the server)

A server's tools stay out of sessions while its tool descriptions differ from the pin, so a server cannot change what its tools claim to do without someone approving it. pin, diff and approve start the server. Exit codes: 0 done, 1 refused or failed, 2 usage. Other venom mcp subcommands are pi's (venom mcp --help).

At start, venom notes once per server the org's OAuth servers you have not signed in to (tracked in ~/.venom/mcp-seen.json). These notices are UI only and never reach the model.

Key Type Default What
mcp object your choice among approved servers
mcp.enabled list of names [] servers the policy leaves off that you turned on; home config only
mcp.disabled list of names [] servers you turned off; lists from every file combine, and a project file may only add here

Enabled servers are the policy's defaults, plus mcp.enabled, minus mcp.disabled.

Generate a plugin from a server

venom plugin scaffold --from-mcp <server> writes a plugin with one typed tool per MCP tool. See Write a plugin.

Troubleshooting

Symptom Cause
a project server does not start the project is not trusted
an org server's tools are missing it is disabled, not signed in (venom mcp connect), or its tools changed since the pin (venom mcp diff)
${VAR} left as written the variable is unset and has no default; a diagnostic names it
a remote server is disabled venom runs with --offline