---
title: Use venom from another agent over MCP
description: Give Claude Code, Codex, Cursor or your own agent venom's browser tools, its web search and a whole venom agent as MCP tools, and know which other interfaces fit better.
section: cookbook
order: 50
audience: [user, builder, agent]
sources: [cli/src/browser-cli.ts, cli/src/mcp-install.ts, packages/harness/src/mcp/server.ts, packages/harness/src/mcp-host.ts, packages/harness/src/session.ts, services/go-orchestrator/internal/search, docs/browser-extension.md, packages/acp/src/cli.ts]
features: []
---

venom can serve three things over the Model Context Protocol (MCP) to an agent that is not venom:

| What | How | Transport |
|---|---|---|
| venom's browser tools, driving your own Chrome | `venom browser mcp` | stdio |
| Web search and page fetch | the orchestrator's `/mcp` | Streamable HTTP |
| A whole venom agent as one tool | a few lines on `McpStdioServer` from `@venom/harness` | stdio |

venom has no built-in "run a venom session" MCP server; the third row is the recipe for building one. For the
other direction, venom using other MCP servers, see [MCP servers](/docs/plugins/mcp.md).

## Browser tools: venom browser mcp {#browser}

Register venom in every agent it finds on this machine, then pair the browser extension once:

```bash
venom browser mcp install              # Claude Code, Cursor and Codex, those installed here
venom browser mcp install --dry-run    # show what would change
venom browser pair                     # the pairing code for the venom extension's popup
```

`install` writes one entry, `venom-browser`, with the command `venom browser mcp`, after a backup of each file
(`<file>.venom-bak-<time>`). It never touches other entries and refuses a file it cannot parse.
`--client claude-code|cursor|codex` picks one; `venom browser mcp uninstall` removes the entry. By hand:

```bash
claude mcp add venom-browser -- venom browser mcp
```

```toml
# ~/.codex/config.toml
[mcp_servers.venom-browser]
command = "venom"
args = ["browser", "mcp"]
```

```json
{ "mcpServers": { "venom-browser": { "command": "venom", "args": ["browser", "mcp"] } } }
```

The JSON shape is what Cursor (`~/.cursor/mcp.json`) and most other clients read.

| Flag | Default | What it does |
|---|---|---|
| `--launch [--headless]` | off | a Chrome venom starts with a temporary profile and its guard proxy, instead of yours |
| `--attach <port>` | off | a Chrome you started with `--remote-debugging-port=<port>` |
| `--relay <host:port>` | `VENOM_BROWSER_RELAY`, else `127.0.0.1:18765` | the relay to reach the extension through |
| `--mode <mode>` | `default` | `default`, `accept-edits`, `yolo` or `plan`; `sudo` is not offered over MCP |
| `--allow`, `--ask`, `--deny <rule>` | none | permission rules, repeatable, e.g. `--allow 'browser(domain:localhost)'` |

Each client process gets its own Chrome window with a tab group named after it. The tools are `browser_navigate`,
`browser_read`, `browser_screenshot`, `browser_click`, `browser_hover`, `browser_type`, `browser_press`,
`browser_scroll`, `browser_wait`, `browser_tabs`, `browser_batch` and `browser_replay`. The permission gate, the
guard against private and metadata addresses, the credential and payment checks and the audit log in
`~/.venom/audit.jsonl` apply as in a venom session. The first action on a site, form submissions and typing into
password or card fields ask the client's user through MCP elicitation; a client without elicitation gets a refusal
naming the rule that would allow the call, so pass rules up front. `venom doctor` shows each client's entry as
aligned, stale, missing or invalid.

## Web search: the orchestrator's /mcp {#search}

The orchestrator serves `web_search` and `fetch_page` at `/mcp`, with the same client key as `/v1`. In a project's `.mcp.json` (Claude Code) or any client that takes HTTP servers:

```json
{
  "mcpServers": {
    "venom-search": {
      "type": "http",
      "url": "http://localhost:8787/mcp",
      "headers": { "Authorization": "Bearer ${VENOM_API_KEY}" }
    }
  }
}
```

Search goes to the backends in its `search:` section (with none, only DuckDuckGo's HTML endpoint; a self-hosted
SearxNG keeps it off third-party APIs), and page fetches
refuse private and loopback addresses ([search and MCP](/docs/orchestrator/search-and-mcp.md#mcp)).

## A venom agent as an MCP tool {#agent}

Expose one tool, `venom_task`, that runs a venom session in a directory and returns its final answer. The
session's permission asks go to the calling agent's user through elicitation (`mcpApprover`), and cancelling the
call aborts the run.

```ts
// venom-agent-mcp.ts  (run with: node venom-agent-mcp.js)
import { createVenomSession, McpStdioServer, mcpApprover, provider, type McpToolProvider } from "@venom/harness";

let server: McpStdioServer | undefined;

const tools: McpToolProvider = {
  list: () => [{
    name: "venom_task",
    description: "Hand a coding task to a venom agent working in a directory. Returns its final answer.",
    inputSchema: {
      type: "object",
      properties: {
        goal: { type: "string", description: "What to do, in one or two sentences" },
        cwd: { type: "string", description: "Absolute path of the repository to work in" },
      },
      required: ["goal", "cwd"],
    },
  }],
  async call(name, args, ctx) {
    if (name !== "venom_task") return { content: [{ type: "text", text: `unknown tool ${name}` }], isError: true };
    const session = await createVenomSession({
      cwd: String(args.cwd),
      mode: "accept-edits",                        // edits go ahead; commands ask the caller's user
      compat: false,
      provider: provider.providerOptionsFromEnv(process.env),
      approve: mcpApprover(() => server),
    });
    const stop = () => void session.session.abort();
    ctx.signal.addEventListener("abort", stop, { once: true });
    const off = session.subscribe((e) => {
      if (e.source === "session" && e.event.type === "tool_execution_start") ctx.progress?.(`venom: ${e.event.toolName}`);
    });
    try {
      return { content: [{ type: "text", text: await session.prompt(String(args.goal)) }] };
    } catch (err) {
      return { content: [{ type: "text", text: String(err) }], isError: true };
    } finally {
      off();
      ctx.signal.removeEventListener("abort", stop);
      session.dispose();
      await session.harness.close();
    }
  },
};

server = new McpStdioServer({
  name: "venom-agent",
  version: "0.1.0",
  instructions: "venom_task runs a full coding agent; give it a self-contained goal and the repository path.",
  tools,
  input: process.stdin,
  output: process.stdout,
  log: (line) => process.stderr.write(`${line}\n`),
});
await server.start();
```

Register it like any stdio server, with the model endpoint in its environment:

```bash
claude mcp add venom-agent --env VENOM_BASE_URL=http://localhost:8787/v1 --env VENOM_API_KEY=… \
  -- node /path/to/venom-agent-mcp.js
```

Notes:

- stdout is the protocol stream. Anything else must go to stderr; the harness's own notices already do.
- `McpStdioServer` speaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, handles several
  calls at once, `notifications/cancelled` (the `ctx.signal` above) and progress notifications when the client
  sent a progress token.
- The session reads no `CLAUDE.md`, hooks or project MCP servers with `compat: false`. Drop it if you want the
  repository's own instructions, after deciding whether you trust the repository
  ([Claude Code compatibility](/docs/harness/claude-code-compat.md)).
- To serve pi tool extensions directly instead of a whole session, `hostExtensionTools(harness, factories, opts)`
  turns their tools into an `McpToolProvider`; `browserMcpServer()` is how `venom browser mcp` is built.

## When MCP is not the right interface {#other}

| You want | Use |
|---|---|
| An editor (Zed and other ACP clients) to use venom as its agent, with diffs and approvals in the editor | `venom acp` (the Agent Client Protocol on stdio), for example `venom acp --mode accept-edits --model venom-smart` |
| A program to run many long sessions, follow their events and answer approvals over HTTP | `venom serve` ([server API](/docs/server-api.md)) |
| A script or CI job to run one prompt and read the result | `venom -p "…"`, with `--json` for an event stream ([headless](/docs/cli/headless.md)) |
| Another agent to call venom's models | the orchestrator's OpenAI-compatible `/v1` ([orchestrator](/docs/orchestrator.md)) |

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| Every browser action is refused with a rule in the message | The client has no elicitation support. Start the server with `--allow '<that rule>'`, or add it to `~/.venom/permissions.json` |
| `venom browser mcp install` reports a file invalid | It is JSON with comments, or Codex's table is not in the expected shape. Edit it by hand with the shapes above |
| The browser tools say no extension is connected | Pair it: `venom browser pair`, then `venom browser status` |
| `/mcp` answers `401` | Send the orchestrator's client key as `Authorization: Bearer` |
| Your MCP server dies on the first call | Something wrote to stdout. Send logs to stderr |

## Related {#related}

- [MCP servers in venom](/docs/plugins/mcp.md): the other direction.
- [Your own tools and approvals](/docs/harness/tools-and-approvals.md).
- [Search and MCP on the orchestrator](/docs/orchestrator/search-and-mcp.md).
