Hooklistener

MCP setup · Codex

Hooklistener MCP server for Codex

Run codex mcp add hooklistener --url https://app.hooklistener.com/api/mcp --oauth-resource https://app.hooklistener.com/api/mcp, then codex mcp login hooklistener --scopes full_access to sign in with your browser. Use --scopes read_only if Codex should only inspect traffic. Codex CLI, the IDE extension and the ChatGPT desktop app share the same config.toml, so one setup covers all three.

Setup checked against Codex docs, September 2026

Terminal
codex mcp add hooklistener \
  --url https://app.hooklistener.com/api/mcp \
  --oauth-resource https://app.hooklistener.com/api/mcp

codex mcp login hooklistener --scopes full_access
Add command
codex mcp add <name> --url <url>
Config file
~/.codex/config.toml or .codex/config.toml (trusted projects)
Transport
Streamable HTTP (--url); there is no --transport flag
Sign-in
codex mcp login with OAuth in the browser
Read-only
--scopes read_only

Setup

Connect Codex step by step

  1. 01

    Add the server

    --url is what makes it a Streamable HTTP server. --oauth-resource tells Codex which resource to request the token for; Hooklistener checks that the token was issued for its MCP URL.

    Terminal
    codex mcp add hooklistener \
  --url https://app.hooklistener.com/api/mcp \
  --oauth-resource https://app.hooklistener.com/api/mcp
  2. 02

    Check what it wrote

    The command adds a block to ~/.codex/config.toml. You can also write it by hand, or put it in .codex/config.toml inside a trusted project.

    ~/.codex/config.toml
    [mcp_servers.hooklistener]
url = "https://app.hooklistener.com/api/mcp"
oauth_resource = "https://app.hooklistener.com/api/mcp"
  3. 03

    Sign in with a scope

    codex mcp login opens the browser. --scopes sets exactly what the token may do. On a remote box, add --no-browser: Codex prints the authorization URL and waits for you to paste the callback URL.

    Terminal
    codex mcp login hooklistener --scopes full_access
# or, inspection only:
codex mcp login hooklistener --scopes read_only
  4. 04

    Check that it connected

    codex mcp list shows configured servers. Inside the Codex TUI, /mcp lists the active servers and their tools.

    Terminal
    codex mcp list

Read-only access

Codex is the one client where picking the scope is a single flag. Log in with --scopes read_only and Hooklistener issues a token that can search, wait, diff, validate and diagnose but never create, replay, forward, send or delete. Common credentials in payloads are masked in results. To switch later, run codex mcp login again with the other scope.

Terminal
codex mcp login hooklistener --scopes read_only

Try it

What to ask Codex

Plain-language requests work; Codex picks from Hooklistener's 67 tools. These are the ones each prompt usually calls.

Why did the GitHub push webhooks fail last night? Find the failures and tell me what the sender retried.

Works with a read-only token: Codex reads the captures and explains the failure without touching anything.

  • list_requests
  • diagnose_request
  • investigate_request_retries

Diff the last successful invoice.paid webhook against the one that returned 500 and point to the field my handler chokes on.

Codex compares headers and body field by field and maps the difference to your handler code.

  • diff_requests
  • get_request

Check every captured order webhook against schemas/order.json and list the ones that fail.

JSON Schema validation runs on Hooklistener's side; Codex gets back the failing paths.

  • list_requests
  • validate_request

Replay the failed request to my local server through the CLI and keep going until it returns 200.

Needs full_access. Codex fixes the handler, replays through hooklistener listen, and repeats.

  • replay_request
  • wait_for_request

Troubleshooting

When Codex doesn't connect

error: unexpected argument '--transport'
Codex has no --transport flag. Pass --url and Codex treats the server as Streamable HTTP. Instructions written for Claude Code or Gemini CLI do not carry over.
A blocking wait times out in Codex first
By default the wait tools return a task right away, so they return well inside the tool timeout. With blocking: true they hold the call open for up to 60 seconds, which equals Codex's default tool_timeout_sec. Give it some headroom. Slow first connections can also hit startup_timeout_sec, which defaults to 10.
~/.codex/config.toml
[mcp_servers.hooklistener]
url = "https://app.hooklistener.com/api/mcp"
oauth_resource = "https://app.hooklistener.com/api/mcp"
tool_timeout_sec = 90
startup_timeout_sec = 20
The project's .codex/config.toml is ignored
Codex only reads project-scoped config in trusted projects. Trust the project, or move the block to ~/.codex/config.toml.
Login succeeds but tool calls return invalid_token
Make sure oauth_resource is set to the MCP URL exactly as shown. Hooklistener rejects tokens issued for a different resource. Run codex mcp login again after fixing it.

FAQ

Codex and Hooklistener: common questions

Does Codex support OAuth for remote MCP servers?

Yes. codex mcp login <name> runs the OAuth flow in your browser, and --scopes chooses which scopes to request. Hooklistener offers full_access and read_only.

Where is the Codex MCP config?

In ~/.codex/config.toml under [mcp_servers.<name>], or in .codex/config.toml for trusted projects. The Codex CLI, the IDE extension and the ChatGPT desktop app share it.

Can I run Codex with Hooklistener in CI without a browser?

Yes. Use --bearer-token-env-var HOOKLISTENER_API_KEY when adding the server (or bearer_token_env_var in config.toml) and set the variable to an hklst_ API key. API keys always have full access, so use them only where you trust the pipeline.

How do I give Codex read-only access?

Log in with codex mcp login hooklistener --scopes read_only. Codex can then inspect, search, wait for and diagnose webhooks, but every write tool is refused.

Keep going

More on the MCP server

Server URL: https://app.hooklistener.com/api/mcp

Other clients

Set up Hooklistener in another tool

Give Codex a webhook URL it can watch

The free plan includes the MCP server, 1 debug endpoint, 1 email inbox and 1 uptime monitor. No credit card.

Start freeSee all MCP tools