Direct answer
Run codex mcp add linear --url https://mcp.linear.app/mcp, complete the Linear sign-in, then run codex mcp list or open /mcp in the Codex terminal interface to confirm the server is active.
Connect Linear MCP to Codex in three steps
Linear MCP Codex setup is the process of connecting a local Codex client to Linear's MCP server. The authorized connection gives Codex access to issue context through your account. The quickest setup is one command, one sign-in, and one connection check.
This is the local MCP path. It is designed for the ChatGPT desktop app, Codex CLI, and Codex IDE extension. These clients share MCP configuration on the same Codex host, so you do not need to register the same server separately in each client.
- Add the server: run codex mcp add linear --url https://mcp.linear.app/mcp.
- Sign in: complete the Linear authorization flow for the account whose issues Codex should access.
- Confirm the connection: run codex mcp list or use /mcp in the Codex terminal interface.
Connect Linear to local Codex
Four steps take Codex from an MCP server entry to issue context that the user can review.
- Add server: Register the Linear MCP URL in Codex.
- Sign in: Complete Linear OAuth for the signed-in account.
- Confirm: Check the server with codex mcp list or /mcp.
- Ask: Name the issue and the exact read or write task.
Choose local MCP or Codex for Linear cloud delegation
You can connect Linear and Codex in two different ways. Choose by where you want the work to start.
The two modes can support the same team, but they are not interchangeable. Local MCP uses the MCP server configured on your Codex host. Cloud delegation depends on the Codex for Linear integration, a connected repository environment, and the workspace settings described in OpenAI's Linear documentation.
- Use local MCP in the Codex desktop app, CLI, or IDE extension. It lets the current task read or update Linear.
- Use Codex for Linear when work should start inside an issue. Assign the issue to Codex or mention @Codex to create a cloud task.
Add the Linear MCP server with the Codex CLI
From a terminal, run the recommended command. The server name is linear, and the URL points Codex to Linear's streamable HTTP MCP endpoint.
Complete the sign-in that follows. OAuth connects the MCP server to your Linear account. If the authorization does not start or was interrupted, run codex mcp login linear.
codex mcp add linear --url https://mcp.linear.app/mcpConfigure the server manually in config.toml
If you manage Codex configuration directly, open ~/.codex/config.toml, add the server entry below, then run codex mcp login linear to complete authorization.
User-level configuration is the simplest choice when you use Linear across repositories. Codex also supports project-scoped .codex/config.toml files in trusted projects. Use project scope only when the server should be available for that repository rather than every local Codex task.
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"Confirm the connection before using an issue
Run codex mcp list and check that linear appears. In the Codex terminal interface, /mcp shows active MCP servers. A listed server confirms that Codex has the configuration; it does not prove that every requested Linear action is authorized.
Start with a small read request that names one issue, for example: “Read BD-394 and summarize its acceptance criteria, status, and related issues. Do not change Linear.” A bounded read confirms that the account can reach the expected workspace and keeps the first test reversible.
After the read works, state any write clearly: the issue identifier, the field or comment to change, and the expected result. Review the proposed update before it is saved when the change affects status, ownership, scope, or other people.
Use Linear and Better Design together in one Codex task
The two servers solve different parts of product work. Issue context, status, relations, and discussion come from Linear. Better Design supplies visual principles, UX guidance, design systems, components, and review rules. Codex can use both while the repository remains the source of truth for implementation.
Connect Better Design as a separate MCP server from the Codex install page. Keeping the servers separate makes their roles clear: Linear manages work context, while Better Design guides and reviews interface decisions.
- Select the Linear issue and read its relations before editing files.
- Compare the issue with the current branch, repository code, and linked evidence.
- Load the Better Design visual and UX guidance that matches the requested interface work.
- Implement one coherent change using the project's tokens and components.
- Run the repository checks and the Better Design review rules.
- Return the evidence to Linear without marking unshipped work as done.
Tell Codex what to read before it writes
A connected tool does not remove the need for a precise task. Give Codex the issue identifier and the boundary of the requested work. Ask it to inspect the issue description, relations, attachments, current status, and repository instructions before making changes.
A useful request is: “Read BD-394 and its related issues. Compare the acceptance criteria with this repository. Draft an implementation plan, but do not edit files or Linear yet.” The next request can authorize a narrower change after you review that plan.
- Name the team or workspace when similar issue keys may exist.
- Say whether the task is read-only, a draft, or an approved write.
- State which repository and branch contain the implementation.
- List checks that must pass before the issue can move state.
- Keep secrets, access tokens, and private customer data out of issue comments.
Fix common Linear MCP Codex problems
- The Linear server is missing: run codex mcp list. If linear is absent, rerun the add command or inspect ~/.codex/config.toml for the [mcp_servers.linear] entry and the exact URL https://mcp.linear.app/mcp.
- The server is listed but Linear is not authorized: run codex mcp login linear and complete the browser authorization. Sign in with the account that belongs to the Linear workspace you expect Codex to use.
- You expected work to start from a Linear comment: local MCP does not install cloud delegation. To start a cloud task with @Codex or issue assignment, install Codex for Linear in Codex settings, then connect the repository environment described in OpenAI's setup guide.
- Codex found the wrong issue or repository: use the full issue identifier and name the repository. Ask for a read-only summary first. For cloud delegation, OpenAI recommends naming the repository in the Linear comment when the automatic choice is ambiguous.
Steal this workflow
Run this guide in your own assistant. The prompt carries the guide link and the workflow summary, so the assistant can adapt it to your project.
Read the guide "Linear MCP Codex setup: connect issues to local work" at https://better-design.com/guides/connect-linear-mcp-to-codex and help me apply it to my project.
Run codex mcp add linear --url https://mcp.linear.app/mcp, complete the Linear sign-in, then run codex mcp list or open /mcp in the Codex terminal interface to confirm the server is active.
Start by asking what I am building and which tools I use. Then walk me through the workflow step by step, adapted to my answers.Claude and ChatGPT open with the prompt filled in. Gemini copies the prompt to your clipboard first, so paste it when the app opens.
Questions
Does Linear MCP work in the Codex app, CLI, and IDE extension?
Yes. OpenAI documents MCP support for the ChatGPT desktop app, Codex CLI, and Codex IDE extension. They share MCP configuration for the same Codex host.
Is Linear MCP the same as Codex for Linear?
No. Local MCP connects Codex clients to Linear tools and context. Codex for Linear starts cloud work from issue assignment or an @Codex mention.
Where does Codex store the Linear MCP configuration?
The default user-level file is ~/.codex/config.toml. Trusted projects can also define project-scoped MCP servers in .codex/config.toml.
Can Codex use Better Design and Linear MCP together?
Yes. Configure each as its own MCP server. Get issue context and workflow updates from Linear. Use Better Design for design-system selection, interface guidance, components, and review rules.
Should Codex update Linear automatically after every task?
Only when the workflow and permissions are clear. Read the issue first, make the requested repository change, run the required checks, then post evidence or change status according to the team's rules. Do not mark work done before it is merged or shipped when the team uses Linear as a delivery ledger.