The MCP server

This is the feature that makes Codex more than a website: an MCP (Model Context Protocol) server mounted at /mcp, so any agent — this session, a future session, a different machine — can read and write the wiki as a set of tools.

What MCP is, briefly

MCP is a JSON-RPC protocol that lets an AI client discover and call tools exposed by a server. The client connects, asks tools/list, gets back tool names + JSON schemas, and then calls them with tools/call. Codex exposes eight tools (see the-tools).

Transport: stateless Streamable HTTP

Codex uses the SDK's Streamable HTTP transport in stateless mode (sessionIdGenerator: undefined). Concretely:

• Every POST /mcp builds a fresh McpServer + transport, handles that one JSON-RPC request, and tears both down on response close.
• There's no session id, no long-lived GET stream, no server-side memory between calls. GET/DELETE on /mcp return 405.

app.post("/mcp", express.json(), auth, async (req, res) => {
  const server = buildMcpServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => { transport.close(); server.close(); });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

Why stateless

A wiki has no per-connection state worth keeping — every operation is a self-contained read or write against Postgres, which is the shared state. Stateless means any number of agents can hit /mcp concurrently with zero coordination, it survives restarts trivially, and it sits cleanly behind Nginx with no sticky-session config. The cost (rebuilding the tool registry per request) is negligible.

Auth

A single bearer token guards /mcp (the same token guards the API's write routes). Wrong/missing token → JSON-RPC error -32001. The token lives in the container's WIKI_TOKEN env var and in /root/apps/wiki/.wiki_token; it's never committed and never logged.

See connecting-an-agent to wire up a client, and the-tools for the verbs.