How to Add MCP Servers to Codex: Step-by-Step Configuration Guide

Use the codex mcp add CLI command to register a Model Context Protocol server, enable the rmcp_client feature flag in your configuration, authenticate with the service if required, and restart Codex to load the available tools.

Codex extends its capabilities by connecting to external services through MCP servers—lightweight processes that expose callable functions via the Model Context Protocol. This guide documents the exact registration workflow and configuration syntax defined in the ComposioHQ/awesome-codex-skills repository, including commands from the Notion, Linear, and Helium skill implementations.

Architectural Overview

MCP servers act as bridges between Codex and third-party APIs. Each server implements one or more tools (e.g., search_news, Notion:notion-create-pages) and advertises its schema to the Codex client over stdio, SSE, or HTTP transport.

The integration relies on two core components:

• config.toml – Stores the mcpServers dictionary (e.g., { "service": { "url": "..." } }) located at $HOME/.codex/config.toml by default.
• Remote-MCP client – A proxy inside the Codex process that forwards tool calls to registered servers when the rmcp_client feature flag is enabled.

According to the MCP best practices documented in mcp-builder/reference/mcp_best_practices.md, the client handles authentication, pagination, and error translation automatically once configured.

Step 1: Register the MCP Server

Registering a server tells Codex where to find the MCP endpoint. Use the following CLI pattern:

codex mcp add <service> --url <MCP-endpoint>

Common service configurations found in the repository include:

Service	Command	MCP Endpoint
Notion	codex mcp add notion --url https://mcp.notion.com/mcp	https://mcp.notion.com/mcp
Linear	codex mcp add linear --url https://mcp.linear.app/mcp	https://mcp.linear.app/mcp
Helium	codex mcp add helium --url https://heliumtrades.com/mcp	https://heliumtrades.com/mcp

This command writes the entry into the MCP section of your config.toml file. For example, the Notion skill guide at notion-spec-to-implementation/SKILL.md (line 23) specifies the exact URL format shown above.

Step 2: Enable the Remote-MCP Client

After registration, you must enable the remote-MCP client so Codex discovers and invokes the server’s tools. Choose one of these methods:

Via config.toml:

[features]
rmcp_client = true

Via CLI flag:

codex --enable rmcp_client

Both approaches set the rmcp_client feature flag, which instructs Codex to load the mcpServers list at startup.

Step 3: Authenticate the MCP Server

Many MCP servers require OAuth or token-based authentication before exposing tools. After adding the server, run:

codex mcp login <service>

• Notion: codex mcp login notion (opens an OAuth flow in your browser)
• Linear: codex mcp login linear (OAuth flow per the Linear skill at linear/SKILL.md, line 27)

Credentials are stored in the Codex credential store, making tools like Notion:notion-search or Linear:linear-create-issue immediately available after restart.

Step 4: Restart Codex

Configuration is read once at launch. Restart Codex to merge the new tools into the LLM’s toolbox:

codex restart

Or quit and relaunch the application. After restart, the LLM can invoke the server’s tools when their descriptions match user requests.

Manual Configuration Alternative

You can bypass the CLI and edit $HOME/.codex/config.toml directly:

[mcpServers]
notion = { url = "https://mcp.notion.com/mcp" }
helium = { url = "https://heliumtrades.com/mcp" }

[features]
rmcp_client = true

Save the file and restart Codex to apply changes.

Complete Configuration Examples

Notion MCP Setup

# Register the Notion MCP server

codex mcp add notion --url https://mcp.notion.com/mcp

# Enable remote MCP client (once per user)

codex --enable rmcp_client

# Authenticate with Notion

codex mcp login notion

# Restart to apply

codex restart

Source: notion-spec-to-implementation/SKILL.md (line 23).

Linear MCP Setup

codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear
codex restart

Source: linear/SKILL.md (line 27).

Helium MCP Setup (No Authentication)

The Helium MCP server (helium-mcp/SKILL.md) provides read-only market data without requiring login:

codex mcp add helium --url https://heliumtrades.com/mcp
codex --enable rmcp_client
codex restart

Summary

• Add servers using codex mcp add <service> --url <endpoint> or edit config.toml manually.
• Enable the client by setting rmcp_client = true in [features] or using --enable rmcp_client.
• Authenticate via codex mcp login <service> for OAuth-protected endpoints like Notion and Linear.
• Restart Codex after configuration changes to load the new tool schema into the LLM context.
• Reference files: notion-spec-to-implementation/SKILL.md, linear/SKILL.md, and mcp-builder/reference/mcp_best_practices.md define the underlying protocol and exact command syntax.

Frequently Asked Questions

What transport protocols does Codex support for MCP servers?

Codex supports stdio, Server-Sent Events (SSE), and HTTP transports. The remote-MCP client handles the connection layer automatically once the URL is registered in config.toml, as specified in mcp-builder/reference/mcp_best_practices.md.

Why must I restart Codex after adding an MCP server?

Codex reads the mcpServers configuration and initializes the remote-MCP client only once at startup. Because the tool schema is merged into the LLM’s context at launch, a restart is required to recognize newly added servers or configuration changes.

Where does Codex store MCP server configurations?

Configurations are stored in the MCP section of $HOME/.codex/config.toml (or your platform’s equivalent Codex config directory). The CLI command codex mcp add writes to this file automatically, but you can edit it manually using TOML syntax under the [mcpServers] header.

Do all MCP servers require authentication?

No. While services like Notion and Linear require OAuth login via codex mcp login, read-only servers such as the Helium MCP (helium-mcp/SKILL.md) work immediately after registration without additional credentials. Check the specific skill documentation to determine if authentication is mandatory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}