Start for free

Codex MCP integration

What is Model Context Protocol (MCP)?

MCP is a standardized protocol that allows AI assistants like Codex to securely access structured data from other applications. When you integrate Alloy with Codex via MCP, Codex can use Alloy session links to retrieve the context behind a prototype or dev session.

With the Alloy MCP integration, Codex can:

  1. Resolve Alloy session links: Paste an Alloy session URL and Codex can identify the matching session in your workspace.
  2. Read chat history: Codex can retrieve the messages from an Alloy session so it understands the prompts and decisions behind the work.
  3. Inspect code context: Codex can list session files and retrieve file content, including before-and-after diffs for dev sessions.

Setting up Codex with OAuth

Codex can connect to Alloy over OAuth. This is the recommended setup because you do not need to create an MCP key or store a bearer token in your shell environment.

1. Add the Alloy MCP server

Run the following command:

codex mcp add alloy --url https://mcp.alloy.app/mcp

This adds an MCP server named alloy to your Codex config.

If you already have an alloy MCP server configured with a bearer token, remove it first:

codex mcp remove alloy
codex mcp add alloy --url https://mcp.alloy.app/mcp

2. Authorize Alloy

Run:

codex mcp login alloy

Codex opens an Alloy authorization page in your browser. Sign in to Alloy if prompted, authorize Codex to access your workspace, then return to Codex.

Once authorized, Codex will have secure access to Alloy session context for your workspace.

Setting up Codex with an MCP key

You can also connect Codex with an Alloy MCP key. This is useful when you want to manage access with a workspace-scoped key instead of using browser-based OAuth.

1. Generate an MCP key in Alloy

  1. Navigate to your workspace settings in Alloy.
  2. Select MCP from the sidebar.
  3. Click Create key.
  4. Copy the generated MCP key.

MCP keys are workspace-scoped. Codex can only access sessions that belong to the workspace associated with the key.

2. Export your MCP key as an environment variable

Codex reads the MCP key from an environment variable rather than embedding it directly in the config file. Add the following line to your shell profile, such as ~/.zshrc, ~/.bashrc, or equivalent:

export ALLOY_MCP_API_KEY="<YOUR API KEY HERE>"

Replace <YOUR API KEY HERE> with the MCP key you generated in Alloy, then reload your shell, for example with source ~/.zshrc, or open a new terminal so the variable is picked up.

3. Configure Codex with the MCP key

Codex reads its MCP server configuration from ~/.codex/config.toml. Open that file in your editor, creating it if it doesn't exist, and add the following entry:

[mcp_servers.alloy]
bearer_token_env_var = "ALLOY_MCP_API_KEY"
enabled = true
url = "https://mcp.alloy.app/mcp"

Save the config and restart any running Codex sessions. Once connected, Codex will have secure access to Alloy session context for your workspace.

Using Codex with Alloy

With the integration set up, you can paste Alloy links into Codex and ask questions about the session. Alloy session URLs can be provided as full URLs, such as https://alloy.app/.../p/.../edit or https://alloy.app/.../p/dev/....

You can ask Codex questions like:

  • "Summarize the chat history for this Alloy session: https://alloy.app/.../p/.../edit"
  • "What files changed in this dev session, and what are the important diffs? https://alloy.app/.../p/dev/..."
  • "Use the code context from this Alloy session to explain how the prototype works."
  • "Pull the chat messages from this Alloy session and turn the decisions into implementation notes."

Available Alloy MCP context

The Alloy MCP server is centered around Alloy sessions. Depending on the session type, Codex can access:

  • Session metadata, including the session title, type, timestamps, status, and related workspace context.
  • Chat messages from a specific session, ordered from oldest to newest.
  • File lists for prototype and dev sessions.
  • Prototype session file content.
  • Dev session before-and-after file diffs for files changed during the session.

This lets Codex answer questions using the same context your team sees in Alloy without requiring you to manually copy messages, files, or diffs into the conversation.

Troubleshooting

If Codex cannot access Alloy session context, check the following:

  • For OAuth, run codex mcp login alloy and complete the browser authorization flow.
  • For MCP keys, confirm the MCP key is exported as ALLOY_MCP_API_KEY in the shell where Codex starts.
  • Confirm the session belongs to the workspace you authorized or the workspace where the MCP key was created.
  • Restart Codex after changing the MCP config or environment variable.
  • Make sure the MCP server URL is https://mcp.alloy.app/mcp.