How to Connect Linear to Codex with the Linear MCP Server

Published August 12, 2026 · by the AQ team

Connecting Linear to Codex takes one command and one login. Run codex mcp add linear --url https://mcp.linear.app/mcp in your terminal, then complete Linear's OAuth sign-in when Codex prompts you (or run codex mcp login linear to start it yourself). Linear hosts its MCP server centrally, so there is nothing to install, no process to keep running, and no API key to paste for the default flow. Once connected, Codex can read, create, and update Linear issues, projects, and comments directly from your session, and the same configuration is shared by the Codex CLI, the IDE extension, and the ChatGPT desktop app.

What you are connecting

MCP (Model Context Protocol) is the open standard AI tools use to talk to external systems. Linear ships an official remote MCP server at https://mcp.linear.app/mcp: your client connects over Streamable HTTP, authenticates with OAuth 2.1 using dynamic client registration, and gets a set of tools scoped to your Linear workspace. Because Linear operates the server, you never clone a repository or manage a local process, and new capabilities arrive without you updating anything. As of August 2026 the server covers finding, creating, and updating issues, projects, and comments, and Linear's February 2026 update extended it to initiatives, project milestones, project updates, and project labels.

On the Codex side, remote MCP servers are supported natively. Codex speaks both stdio (a local process it launches) and Streamable HTTP (a URL it connects to); the Linear server is the second kind, which is why the whole setup is one flag. Two endpoint details worth knowing before you start:

• Read-only variant. https://mcp.linear.app/mcp/readonly only ever exposes read tools. Use it when Codex should consult Linear but never write to it.
• SSE is deprecated. Linear's older https://mcp.linear.app/sse endpoint is being removed. New setups should always use the /mcp endpoint over Streamable HTTP, which Codex supports.

Step 1: Add the server

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

The name argument (linear here) is your local label for the server; letters, numbers, hyphens, and underscores are allowed. This writes an entry to ~/.codex/config.toml. If you prefer editing configuration by hand, the equivalent is:

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

Step 2: Sign in with OAuth

Linear's own setup instructions note that adding the server prompts you to log in with your Linear account. If it does not, or you skipped it, run:

codex mcp login linear

Codex performs an OAuth authorization code flow with PKCE: it opens your browser to Linear's consent screen, you approve, and the token is stored locally. There is no client ID to configure because Linear supports dynamic client registration. The grant acts as you: Codex can see and change what your Linear account can see and change, within the tools the server exposes.

Step 3: Verify and use it

codex mcp list

A healthy setup shows the server with its URL; codex mcp remove linear deletes it if you need to start over. Then start a Codex session and use plain prompts. Patterns that hold up well:

• Issue as context: "Implement ENG-142. Read the issue and its comments first, then make the change." Codex fetches the issue itself instead of you pasting it.
• Status and summary: "Mark ENG-142 In Review and comment with a summary of what changed."
• Filing from the terminal: "Create a bug in the Payments project titled 'Refund edge case crash' with repro steps from the stack trace above."
• Queue triage: "List my assigned Linear issues and flag which are small enough to finish today."

A useful convention: have Codex include the Linear issue ID in branch names and PR titles. Linear links the PR to the issue automatically, so status flows without extra prompting.

If the server does not load: the rmcp feature flag

Remote Streamable HTTP servers ride on Codex's newer Rust MCP client. Current releases enable it by default, but Linear's setup page notes that some Codex versions need the feature switched on first. If codex mcp list does not show your server or tools never appear in a session, add this to ~/.codex/config.toml and restart Codex:

[features]
rmcp_client = true

Older releases used the top-level spelling experimental_use_rmcp_client = true instead. If neither helps, upgrading Codex is usually the real fix, since remote MCP support has improved release over release through 2026.

Authenticating with an API key instead

OAuth is right for interactive use, but headless environments (CI jobs, containers, scripted runs) cannot open a browser. The Linear MCP server also accepts direct bearer authentication, and Codex can read the token from an environment variable so it never lands in your config file:

export LINEAR_API_KEY=lin_api_...
codex mcp add linear --url https://mcp.linear.app/mcp   --bearer-token-env-var LINEAR_API_KEY

Personal API keys are created in Linear under Settings, then Account, then Security & Access. As of August 2026 they support fine-grained permissions (full access, or restricted combinations like read plus create issues and create comments) and can be limited to specific teams. A key scoped to one team with read and comment permissions is a sensible floor for an agent that should consult Linear but not restructure it; pair a restricted key with the readonly endpoint when you want belt and suspenders.

Sharing the setup, and where it does not reach

Everything above configures your machine, and it carries further than you might expect: the Codex CLI, the Codex IDE extension, and the ChatGPT desktop app read the same ~/.codex/config.toml, so one setup covers all three. To make the server part of a repository instead, Codex also reads a project-scoped .codex/config.toml, but only for projects you have marked trusted; teammates still authenticate individually, and no shared secret belongs in the repo.

The boundary to know: Codex cloud tasks run on OpenAI's infrastructure and do not inherit the MCP servers configured on your laptop. As of August 2026, this per-machine setup applies to local Codex surfaces. If your team leans on cloud or long-running agent sessions, that is where a shared execution layer starts to matter, which is the last section of this guide.

Troubleshooting

• Login never completes. The OAuth callback needs a local browser. On a remote box over SSH, use API-key auth with --bearer-token-env-var instead, or forward a port for the callback.
• Server added but no tools in the session. Enable the rmcp feature flag above, restart Codex fully (including the IDE extension), and re-check codex mcp list.
• Authentication asked for again. Tokens expire; codex mcp login linear re-authenticates in place. If it loops, remove and re-add the server, and revoke the stale authorization in Linear's settings before approving fresh.
• Works in the CLI but not the IDE extension. Both read the same config, but the extension picks it up on restart; reload the editor window after any config change.

Where AQ fits: MCP wires up one developer, intake wires up the team

Everything above connects Linear to one developer's Codex. Each teammate adds the server, authenticates, and drives the loop by prompting: fetch the issue, do the work, move the status. That is exactly right for individual sessions. What it does not give a team is a shared starting point: the link between "this issue should be worked by an agent" and "a session exists for it, and the team can see it" still lives in whoever happens to type the prompt, on whichever laptop happens to be open.

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ connects to Linear at the workspace level instead of the client level: label an issue "ai-task" and a workspace appears for it in AQ, on its own isolated git worktree, visible to the team. Status syncs both ways, ownership follows the Linear assignee, and a human starts the agent (nothing auto-launches). Inside that workspace, Codex runs as the real CLI under your own OpenAI account, in a persistent tmux session on your team's VM, so the session survives a closed laptop and teammates can open the same workspace and watch it live. The MCP setup from this page still applies inside the session: AQ handles issue-to-workspace, MCP handles issue-to-context.

The two compose rather than compete. One developer with Codex on a laptop needs only this page. A team routing real Linear work through agents every day can see how the intake side works in AQ's Linear integration docs, and the Claude Code twin of this setup lives at adding the Linear MCP server to Claude Code.