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.
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 |
Related
- Claude Code plugins
- Install and manage plugins (the org marketplace also lists MCP packages)