Codex MCP setup: connect Invoke Human

Codex reads MCP servers from config.toml. Invoke Human is a URL, not a local process, and sign-in is OAuth.

Updated October 17, 2026

1. Point Codex at the server. Add a streamable HTTP server named invoke-human with the URL https://invokehumantool.com/mcp.
2. Give the tool call time. Set tool_timeout_sec above Codex's 60 second default so a human answer is not cut off.
3. Sign in. Run codex mcp login invoke-human and finish OAuth. The scope is handoffs.
4. Ask for a handoff. Tell Codex to call send_handoff, send_ui_handoff, send_html_handoff, validate_ui, share_handoff, delegate_handoff, get_handoff_status, get_handoff_result, or wait_for_handoff, then answer in the iPhone, iPad, or Mac app.

Codex, the ChatGPT desktop app, and the Codex IDE extension share one MCP config. Add the server once. OpenAI documents this on the Codex MCP page. ChatGPT on the web is a different path, covered in the ChatGPT guide.

The endpoint is https://invokehumantool.com/mcp. How that URL answers a request with no token is the remote MCP guide.

Add the server

Pick whichever surface you actually use. They write the same file.

CLI and config file. Codex stores MCP servers in ~/.codex/config.toml, or in .codex/config.toml for one trusted project. A streamable HTTP server needs url. auth defaults to oauth, which is what you want here.

[mcp_servers.invoke-human]
url = "https://invokehumantool.com/mcp"
tool_timeout_sec = 600

600 is an example. Codex documents a default tool_timeout_sec of 60. A person answering a worksheet often takes longer than a minute, and the tool call is what is waiting. Set the number to how long you are willing to let that call sit.

ChatGPT desktop. Settings, then MCP servers, then Add server. Choose Streamable HTTP, name it invoke-human, paste the URL, save, and restart. If the row says it needs OAuth, choose Authenticate. /mcp in the composer lists connected servers.

IDE extension. Gear menu, MCP servers, Add server. Same choice: Streamable HTTP and the URL. Save, then restart the extension, then Authenticate if it asks.

You do not need a pre-registered client id. The authorization server metadata for Invoke Human includes a registration_endpoint and does not advertise Client ID Metadata Documents. Codex’s own docs say the automatic choice in that case is dynamic client registration.

Sign in

codex mcp login invoke-human

Finish the browser prompt with the email or Apple ID on the Invoke Human account. The scope on the server is handoffs. If a login ever tries the wrong registration method, force the one the server publishes:

codex mcp login invoke-human --oauth-client-registration dcr

codex mcp list shows the server. In the terminal UI, /mcp lists what is connected.

Codex can also be told to prompt before a tool runs (default_tools_approval_mode on that server). That prompt is Codex asking you, on the machine, whether the tool may run. It is not the handoff. The handoff is the later call that needs a decision, a form, or a worksheet from you.

Use it

Ask for a person in plain language, and name the tool if Codex has several MCP servers:

• send_handoff sends a handoff to the signed-in person, or to other people.
• send_ui_handoff sends a structured form the person answers on a device or a signed link.
• send_html_handoff sends an HTML handoff the person answers by tapping or typing.
• validate_ui checks a UI document before it is sent.
• share_handoff invites more people to a handoff, or forwards it.
• delegate_handoff forwards a handoff to new recipients.
• get_handoff_status reads the type, title, and status of one handoff.
• get_handoff_result fetches the answer, or the current status if it is not finished.
• wait_for_handoff waits until the person finishes that handoff.

Parameter names come from the tool list the server returns after OAuth. This guide does not copy a schema. The same install, in short, is on Support.

The answer comes back to that Codex thread, with attribution for who answered and how. You do the answering in the iPhone, iPad, or Mac app. iPhone and iPad need iOS 17 or later. The app is in TestFlight. Join from the home page. The signed web page is for that one handoff, not a second inbox. See the agent inbox page for what belongs there.

When it fails

A 401 means the login is not done. Run codex mcp login invoke-human again. A timeout while you are still writing is tool_timeout_sec, not a dropped server. If the project file is ignored, Codex only reads .codex/config.toml for trusted projects. Put the block in ~/.codex/config.toml until the project is trusted.

Same server, other clients: Cursor, Claude, ChatGPT.