---
title: MCP servers
description: 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.
section: plugins
order: 70
audience: [user, operator, builder]
sources: [packages/harness/src/compat/mcp.ts, packages/harness/src/compat/mcp-sse-bridge.ts, cli/src/mcp-command.ts, cli/src/mcp-connect.ts, cli/AGENTS.md, docs/venom-config.schema.json]
features: [plugins.mcp]
---

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

```json
// .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](#org) |

`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 {#org}

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.

```bash
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](/docs/plugins/writing.md).

## 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](/docs/plugins/claude-code-plugins.md)
- [Install and manage plugins](/docs/plugins/installing.md) (the org marketplace also lists MCP packages)
