Use venom from another agent over MCP
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.
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.
Browser tools: venom browser mcp
Register venom in every agent it finds on this machine, then pair the browser extension once:
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 popupinstall 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:
claude mcp add venom-browser -- venom browser mcp# ~/.codex/config.toml
[mcp_servers.venom-browser]
command = "venom"
args = ["browser", "mcp"]{ "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
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:
{
"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).
A venom agent as an MCP tool
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.
// 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:
claude mcp add venom-agent --env VENOM_BASE_URL=http://localhost:8787/v1 --env VENOM_API_KEY=… \
-- node /path/to/venom-agent-mcp.jsNotes:
- stdout is the protocol stream. Anything else must go to stderr; the harness's own notices already do.
McpStdioServerspeaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, handles several calls at once,notifications/cancelled(thectx.signalabove) and progress notifications when the client sent a progress token.- The session reads no
CLAUDE.md, hooks or project MCP servers withcompat: false. Drop it if you want the repository's own instructions, after deciding whether you trust the repository (Claude Code compatibility). - To serve pi tool extensions directly instead of a whole session,
hostExtensionTools(harness, factories, opts)turns their tools into anMcpToolProvider;browserMcpServer()is howvenom browser mcpis built.
When MCP is not the right interface
| 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) |
| A script or CI job to run one prompt and read the result | venom -p "…", with --json for an event stream (headless) |
| Another agent to call venom's models | the orchestrator's OpenAI-compatible /v1 (orchestrator) |
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
- MCP servers in venom: the other direction.
- Your own tools and approvals.
- Search and MCP on the orchestrator.