Local stdio MCP server — oh-hai-mcp

The same five tools as the hosted server, run as a local process over stdio. Package @oh-hai/mcp on npm, binary oh-hai-mcp.

# run without installing (the package ships two bins, so name the one you want)
npx -y -p @oh-hai/mcp oh-hai-mcp

# or install globally
npm i -g @oh-hai/mcp
oh-hai-mcp

Requires Node >= 24. On start it prints one line to stderr — oh-hai MCP server ready · hub https://inbox.ohhai.app · tools: oh_hai_notify, oh_hai_ask, oh_hai_task, oh_hai_inbox, oh_hai_list — and speaks JSON-RPC on stdin/stdout.

Configuration (environment)

Variable	Meaning	Default
MA2H_AGENT_TOKEN	Required. The per-agent bearer. Resolved once at startup and bound into the Hub client; never exposed to the model in a tool input, result or error.	—
MA2H_AGENT_ID	Required. The agent id (agnt_…) stamped on outbound envelopes. Must be the id bound to the token, or the Hub answers 403 on every submit. Not defaulted, so a placeholder cannot fail silently later.	—
MA2H_BASE_URL	Hub base URL. Point at a local Hub for development. Trailing slashes are stripped.	https://inbox.ohhai.app
MA2H_TIMEOUT_MS	Per-request timeout, and the per-poll bound inside oh_hai_ask.	10000
MA2H_SESSION_ID	Attach to an existing session (sess_…) instead of registering one. Stdio only — the hosted entry ignores it.	—

The server fails fast — non-zero exit and a stderr message — if MA2H_AGENT_TOKEN or MA2H_AGENT_ID is unset:

oh-hai MCP server failed to start: MA2H_AGENT_TOKEN is required — the MCP server resolves its bearer from the environment (never through an LLM).

There is no agent-id header and no config file; the environment is the whole configuration.

Client setup

Export the two required variables in the environment your MCP client inherits. Never write the token into a committed file.

export MA2H_AGENT_ID=agnt_…
export MA2H_AGENT_TOKEN=…

Claude Code

claude mcp add oh-hai --env MA2H_AGENT_ID=agnt_… -- npx -y -p @oh-hai/mcp oh-hai-mcp

The token is inherited from the environment Claude Code runs in. Or in .mcp.json:

{
  "mcpServers": {
    "oh-hai": {
      "command": "npx",
      "args": ["-y", "-p", "@oh-hai/mcp", "oh-hai-mcp"],
      "env": {
        "MA2H_AGENT_ID": "agnt_…",
        "MA2H_AGENT_TOKEN": "${MA2H_AGENT_TOKEN}"
      }
    }
  }
}

Other clients

Any client that launches stdio MCP servers takes the same three things: the command (npx -y -p @oh-hai/mcp oh-hai-mcp, or oh-hai-mcp after a global install), and the MA2H_AGENT_ID / MA2H_AGENT_TOKEN environment. Cursor and Windsurf use command / args / env under mcpServers; VS Code uses type: "stdio" with command / args / env under servers; Codex uses [mcp_servers.oh-hai] with command, args and env in ~/.codex/config.toml; Gemini CLI uses command / args / env under mcpServers in ~/.gemini/settings.json. Prefer your client's own environment-variable expansion over a literal token.

When to prefer stdio over hosted

• The token should never leave your machine's process environment.
• You are running against a different Hub (MA2H_BASE_URL), for instance a local development Hub.
• You want the server to present a session you opened with the CLI: put the id oh-hai session start --quiet prints into the server's environment as MA2H_SESSION_ID. (Do not reuse the session a running oh-hai bridge is draining — two readers split one mailbox.) The server then drains and sends as that session, and a peer addressing agent:<id>#sess_… reaches this process's oh_hai_inbox. A pinned session is never silently swapped: if it lapses or a human closes it, session-bearing calls fail loudly and tell you to unset or re-point MA2H_SESSION_ID and restart.
• You want one process per agent identity rather than one bearer per request.

Everything else — tool names, schemas, results, the oh_hai_ask wait budget (default 110 s, cap 300 s), the lazy session registration for addressed sends and drains — is identical to the hosted server.

What it is not

It is not a bridge. oh-hai-mcp only acts when a tool is called; nothing wakes the agent when mail arrives. For always-on reachability run the CLI's oh-hai bridge alongside (as a background task, re-run after every exit), or instead. See MCP or CLI?.