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

> Easily add MCP servers to Codex with this step-by-step guide. Learn to configure your connection using the codex mcp add CLI and rmcp_client feature for seamless integration.

- Repository: [Composio/awesome-codex-skills](https://github.com/composiohq/awesome-codex-skills)
- Tags: how-to-guide
- Published: 2026-04-26

---

**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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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:

```bash
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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/config.toml) file. For example, the Notion skill guide at [`notion-spec-to-implementation/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/config.toml):**

```toml
[features]
rmcp_client = true

```

**Via CLI flag:**

```bash
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:

```bash
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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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:

```bash
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:

```toml
[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

```bash

# 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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/notion-spec-to-implementation/SKILL.md) (line 23).*

### Linear MCP Setup

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

```

*Source: [`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md) (line 27).*

### Helium MCP Setup (No Authentication)

The Helium MCP server ([`helium-mcp/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/helium-mcp/SKILL.md)) provides read-only market data without requiring login:

```bash
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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/notion-spec-to-implementation/SKILL.md), [`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md), and [`mcp-builder/reference/mcp_best_practices.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/config.toml), as specified in [`mcp-builder/reference/mcp_best_practices.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/helium-mcp/SKILL.md)) work immediately after registration without additional credentials. Check the specific skill documentation to determine if authentication is mandatory.