PostMQ in Codex.

PostMQ is an MCP server that Codex connects to — not Codex running as an MCP server, and not something that executes inside your editor. The server holds the records: build sessions, decisions, backlog rows, and the typed messages agents hand each other. Codex is the client, and it sees the same 87 tools every client sees — over Streamable HTTP at https://mcp.postmq.com/, or over stdio for a co-located deployment — with a scoped, once-disclosed credential as the bearer on every call. PostMQ speaks standard MCP, so any MCP-capable client can connect; Codex is one of the AI coders we run ourselves, daily, against this same surface — including hand-offs where one agent builds and another reviews, which is the session rendered below. Claude Code is the client the session protocol was written in, and PostMQ in Claude Code is this page’s sibling. The connection here is one TOML table read by all three Codex surfaces — the CLI, the IDE extension and the desktop app share one configuration. And the session protocol is not a Claude Code exclusive any more: the kit installs into Codex’s own surfaces, the two skills under .agents/skills and the session hooks through .codex/hooks.json, written from the same files the Claude Code install writes — the section below covers the install, the two Codex behaviours that shape it, and the instructions-only alternative.

Issue the credential in the mcp_config form and the reveal prints the mcp_config block first, shown once, with a copy button — name, transport, the URL, the Authorization: Bearer header — and the stdio block under it. The [mcp_servers.postmq] table below is that block field for field, in Codex’s shape: the same name and URL, and — where the JSON writes the header out — bearer_token_env_var, which names the environment variable whose value Codex sends as the bearer. The secret never sits in the file; export POSTMQ_CREDENTIAL in the environment the CLI, the extension or the app starts from. Codex’s http_headers option exists for static extra headers, and its auth option defaults to OAuth for servers that use it — PostMQ authenticates with the bearer credential, so the one line is the whole of it. The URL and the env key are rendered from the same module the docs page and the MCP server page render their snippets from, so the clients cannot disagree.

pmq mcp stdio runs the same server over stdio for a self-hosted or co-located deployment. The MCP wire has no Authorization header there, so the credential is process-ambient: the host reads POSTMQ_CREDENTIAL first — the key both entries on this page name — then PMQ_CREDENTIAL, the earlier name kept so an existing local setup keeps working, then the ~/.pmq/credentials file; it re-reads them on every request, so a rotated value is picked up mid-session, and the request fails closed as unauthenticated when none of the three is set. The entry’s env table sets the variable for the process Codex spawns, and startup_timeout_sec and tool_timeout_sec are the entry’s knobs when a start or a call runs long. It still needs a connection to the hosted database — stdio changes the wire, not where the records live — and the pmq CLI is built from source; packaged downloads are not yet published.

codex mcp add registers either form: --url with --bearer-token-env-var writes the streamable HTTP entry — the same two TOML lines above, without opening the file — and --env pairs with a command after -- write the stdio one; the two shapes are mutually exclusive on the command line, as in the file. codex mcp list prints what is registered, whichever way it got there. (codex mcp login exists for OAuth servers; a bearer credential has nothing to log in to.)

On the Claude Code page this protocol appears as two skills, a session-start hook and a session-end hook. Codex has surfaces of its own for both, and the kit now installs into them: the skills become SKILL.md directories under .agents/skills, where Codex finds them by name and description and reads the body when your task matches one; the hooks are wired in .codex/hooks.json. Both clients are written from the same files, so there is one protocol rather than two descriptions of it that drift. The tool names need no translation either — Codex names MCP tools the same way Claude Code does.

Two Codex behaviours shape the install, and both are the client protecting you rather than the kit falling short. Codex reads a project’s .codex/ configuration only once you have marked that project trusted, and it asks you to review a hook once before it will run it — so a freshly installed hook is inert until you approve it, and editing it asks again. And Codex gives a session-end hook one second by default and three at the outside; reading a transcript and reporting it does not fit in that, so the usage reporter is launched by a small wrapper that returns at once and finishes the work in a detached process.

If you would rather install nothing, the protocol is seven tool calls and any MCP-capable client makes them with the same arguments against the same ledger. Codex reads AGENTS.md guidance files, so it can travel as instructions instead — a session-protocol section in your repository’s AGENTS.md that tells the agent when to make each call. The table below is that pattern: the session protocol reduced to the instructions such a file carries and the tool each instruction drives. Two honest notes on that route. PostMQ does not ship an AGENTS.md today — we run the protocol from Claude Code, so the file this section describes is one you write, not one you download; the rows are the pattern, close enough to copy. And the usage row is where the parallel is loosest: an instruction can only report what the client lets the agent see, which is the gap the installed session-end hook closes.