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 integration

Setting up the Codex integration with Alloy requires an Alloy MCP API key and a Codex MCP server entry.

1. Generate an MCP API 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 API key.

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

2. Export your API key as an environment variable

Codex reads the API 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 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

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:

  • Confirm the API key is exported as ALLOY_MCP_API_KEY in the shell where Codex starts.
  • Confirm the session belongs to the same workspace where the API 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.