Verbs

agentproto mcp-bridge

agentproto mcp-bridge [--import <alias|importId>]

A stdio MCP server that proxies to the daemon's HTTP /mcp orchestration endpoint. Stdio-only MCP clients (Codex, Cursor, Claude Desktop, Hermes) can use AgentProto's orchestration tools through this bridge — no third-party bridge needed.

--import <alias|importId>: one imported MCP server

By default the bridge proxies /mcp — every orchestration tool. --import <alias|importId> dials /mcp/imported/<alias|importId> instead: the stdio client sees ONE imported MCP server (for example bureau) under its own native tool names, not the daemon's orchestration tools. The daemon accepts the alias or the import id; same auth and caller identity as /mcp. --import cannot be combined with --surface (exit 2), and its value must be letters, digits, . _ : -.

{
  "mcpServers": {
    "bureau": {
      "command": "agentproto",
      "args": ["mcp-bridge", "--import", "bureau"]
    }
  }
}

install-mcp --import writes such an entry for you.

The bridge connects to the daemon over HTTP (Streamable HTTP transport), pulls the tool list once at startup, then passes listTools, callTool, resources/list, resources/read, and resources/templates/list requests through. Tool JSON schemas are forwarded intact so clients see the real parameter names and types.

Codex Desktop conversation identity

When a tool call carries Codex thread metadata, the bridge connects that call as /mcp?callerSessionId=codex:<thread-id>&host=codex. The daemon registers an external session for that chat, so session_follow can default its follower without the model choosing a session id. The bridge reads the metadata on every call and uses a separate request-local connection; concurrent chats do not share a last-seen identity. Existing callerSessionId URLs take precedence.

Recognized metadata includes _meta["x-codex-turn-metadata"] (an object or JSON string containing thread_id), openai/threadId, openai/thread_id, codexThreadId, codex_thread_id, threadId, thread_id, and thread.id. These are host-supplied MCP metadata, outside the tool's arguments. A host must identify itself as Codex to use the generic thread aliases; namespaced Codex/OpenAI metadata also works with a generic handshake name. A host that does not attach them must be updated to do so. The bridge never derives conversation identity from clientInfo.name, a process-wide CODEX_THREAD_ID, or an old agentproto session id.

Identity alone provides inbox delivery. By default session_follow reports delivery: { mode: "external-inbox", wakesFollower: false, ... }. For allowlisted local chats, the daemon can use experimental Codex Desktop wake to request a notification turn from Desktop.

Configuration

Env varDefaultDescription
AGENTPROTO_MCP_URLhttp://127.0.0.1:<daemon.port>/mcpDaemon /mcp endpoint.

The default port is read from ~/.agentproto/config.json → daemon.port (default 18790). Set AGENTPROTO_MCP_URL explicitly if the daemon runs on a non-standard port.

Registering in a stdio MCP client

{
  "mcpServers": {
    "agentproto": {
      "command": "agentproto",
      "args": ["mcp-bridge"],
      "env": {
        "AGENTPROTO_MCP_URL": "http://127.0.0.1:18790/mcp"
      }
    }
  }
}

For Claude Desktop this goes in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent config path on other platforms.

For Codex, Cursor, and Hermes, configure the MCP server entry in their respective settings using the same shape.

Startup

agentproto mcp-bridge: AGENTPROTO_MCP_URL not set, using http://127.0.0.1:18790/mcp
agentproto mcp-bridge: connected to http://127.0.0.1:18790/mcp, proxying 12 tool(s) over stdio

The process parks forever — StdioServerTransport stays alive until stdin closes or the process is killed. The tool count in the startup message reflects the daemon's current tool set; if the daemon restarts, restart the bridge too.

Errors

If the daemon is not running:

agentproto mcp-bridge: failed to connect to daemon at http://127.0.0.1:18790/mcp —
  Connection refused. Is the daemon running? Start it: agentproto serve

Examples

# Default: reads daemon.port from config, connects to localhost
agentproto mcp-bridge

# Explicit URL for a non-standard port
AGENTPROTO_MCP_URL=http://127.0.0.1:18791/mcp agentproto mcp-bridge

See also