Connect Codex to Linear

What you get

Linear runs its own MCP server at https://mcp.linear.app/mcp. Linear’s docs say it “supports Streamable HTTP transports,” so Codex hits that endpoint directly and there’s no local process to install.

Per those same docs, the server has tools for “finding, creating, and updating objects in Linear like issues, projects, and comments,” and Linear says more functionality is on the way. That list moves, so run codex mcp list after connecting and read the tool names off your own install rather than trusting a hardcoded list on this page.

Setup

Read Connect an MCP server first for the general TOML shape. If the CLI isn’t installed yet, start at Install Codex CLI.

1. Add the server. This is the command Linear’s own docs give:

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

That writes this into ~/.codex/config.toml:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

An entry gets url or command, never both, so there’s no command line for this one.

2. Authenticate with OAuth. Linear’s default is OAuth 2.1 with dynamic client registration. Codex’s auth key already defaults to "oauth", so leave it out and run:

codex mcp login linear

That opens a browser, Linear issues a token for your account, and Codex catches the callback locally.

3. Or use a Linear API key instead. Linear’s docs say the server supports “passing OAuth token and API keys directly in the Authorization: Bearer <yourtoken> header.” Generate a personal API key in Linear, export it in your shell, and name the variable in your config so the key itself never lands in the file:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_API_KEY"

bearer_token_env_var names an environment variable Codex reads when it makes the request. That’s a separate mechanism from the [mcp_servers.<id>.env] sub-table, which passes variables into a local stdio process. A url server never spawns one. See mcp_servers.<id>.env for the stdio side of that.

4. Confirm it initialized.

codex mcp list

You want linear listed with its tools.

Gotchas

Skip the experimental_use_rmcp_client line in Linear’s docs. As of today, linear.app/docs/mcp tells Codex users to add this to ~/.codex/config.toml before connecting:

[features]
experimental_use_rmcp_client = true

Leave it out. The flag is stale twice over. openai/codex #6995 deprecated that name in favor of [features].rmcp_client and is closed. Then #8087, merged December 20, 2025, removed the checks from the codebase entirely, with the reasoning that “with codesigning on Mac, Windows and Linux, we should be able to safely remove features.rmcp_client and use_experimental_use_rmcp_client check from the codebase now.” On any build since then, including the current 0.144.5 (July 16, 2026), the rmcp client is simply what you get and the flag has nothing left to switch on. We didn’t test what current Codex does if you set it anyway, so the honest advice is to omit it rather than to promise it’s harmless.

codex mcp login has an open token-audience bug. openai/codex #13891 is open, labeled auth, bug, and mcp. It reports that the login flow builds the authorize request with scope= but omits the resource indicator, so the authorization server can mint a token for a different audience than the server you’re logging into. In the reporter’s words, login “then reports success, but the resulting token audience is for a different resource than the MCP server being logged into.” If codex mcp login linear succeeds and calls still fail auth, that’s your candidate. Codex does have an oauth_resource key for the server block, but nothing we found confirms setting it works around #13891, so treat that as a thing to try rather than a fix we’ve verified.

Expired tokens don’t refresh on their own. openai/codex #17265 is open: Codex stores a refresh token in ~/.codex/.credentials.json but doesn’t use it automatically once the access token expires. Tool calls start failing auth after an idle stretch and you re-run codex mcp login linear by hand. Worth knowing before you point anything unattended at Linear.

The API key path is documented on both sides. Both OAuth issues above are open, and bearer_token_env_var with a Linear API key is a supported path in Codex’s config reference and in Linear’s docs. Whichever one you pick, the token belongs in an environment variable, never typed into a config.toml you might commit.

Related

• Connect an MCP server: the general stdio/remote shape and the JSON-to-TOML translation table
• mcp_servers.<id>.url: the remote endpoint and its auth keys
• mcp_servers.<id>.env: keeping keys and tokens out of committed config
• mcp_servers.<id>.startup_timeout_sec: launch window if a server is slow to answer
• Install Codex CLI: if you’re setting this up before Codex itself