Direct answer
Linear MCP Codex is a direct connection between OpenAI Codex and Linear's hosted Model Context Protocol server. It lets Codex use authorized Linear tools and live workspace context during a task. Add the official Streamable HTTP endpoint, complete OAuth, verify the server, and test a read request. Start with read-only access unless the workflow truly needs writes. Keep issue selection, scope decisions, approvals, and final status changes under human control.
In short
- Select Linear's hosted /mcp endpoint for read-write access.
- Select the hosted /mcp/readonly endpoint when Codex only needs to inspect work.
- Add the server with the Codex CLI, desktop app, or IDE extension, then complete OAuth.
- Verify the active server before asking Codex to read an issue or project.
- Name exact teams, projects, issue identifiers, and allowed actions in the task.
- Review every proposed write and re-read the changed Linear object afterward.
What does Linear MCP Codex mean?
MCP is a standard way for a client to discover and call tools exposed by a server. In this setup, Codex is the client. Linear hosts the server and exposes authorized operations for issues, projects, comments, and related workspace objects.
The connection does not copy your entire backlog into every prompt. Codex can call available tools when the task needs them. The granted account, OAuth scope, endpoint, server configuration, tool policy, and user approvals determine what is reachable.
Check Linear's current MCP server documentation and supported clients.
Set up Linear MCP in Codex
Choose the direct hosted connection when you only need Linear. A third-party integration layer may suit a broader multi-app workflow, but it adds another service and permission boundary.
- Confirm that Codex is current enough to support Streamable HTTP servers and OAuth.
- Choose read-only or read-write access before adding the server.
- Run: codex mcp add linear --url https://mcp.linear.app/mcp
- Complete the Linear sign-in and authorize the intended workspace and scope.
- Run: codex mcp list, then confirm that linear appears and authentication is valid.
- Open Codex and use /mcp to confirm that the server and tools are active.
- Test a narrow read prompt before asking Codex to change anything.
Prefer read-only access first
For planning, code review, investigation, and requirement lookup, write access is often unnecessary. Add a separate read-only server with: codex mcp add linear-readonly --url https://mcp.linear.app/mcp/readonly. This endpoint only exposes read tools.
Choose the standard /mcp endpoint when the task must create issues, add comments, or update records. Ask for the smallest useful OAuth scope. Codex also supports server tool allow lists, deny lists, and approval modes in config.toml.
Review OpenAI's current Codex MCP configuration and tool-policy options.
Configure it manually when needed
The equivalent config.toml entry is [mcp_servers.linear] with the same hosted /mcp URL. Then run codex mcp login linear. The CLI command is preferable because it reduces formatting mistakes.
OpenAI states that the desktop app, Codex CLI, and IDE extension share MCP configuration for the same Codex host. Restart the active client after a manual change. Project-scoped configuration belongs in .codex/config.toml and only loads for trusted projects.
Verify the connection before real work
A server entry confirms that configuration exists. It does not confirm that the correct workspace, account, scope, or tool set is active. Run a read-only test that names an issue you already know.
Example: Read ENG-123. Return its title, current state, assignee, acceptance criteria, linked issues, and the latest relevant comment. Make no external changes. State which fields were unavailable.
- Confirm that the returned title and state match Linear.
- Check that the issue belongs to the intended workspace and team.
- Ask Codex to name missing fields instead of filling gaps from inference.
- Inspect available tools and remove any that the workflow does not need.
- Keep the first write reversible, small, and easy to verify.
Use an issue-first development workflow
A useful connection changes the order of work. Codex should read the selected issue and its relations before proposing implementation. The issue remains evidence, not automatic authority to alter code or external records beyond the user's task.
- Select the exact Linear issue and read its description, comments, relations, labels, assignee, and state.
- Compare that record with the repository, linked pull requests, commits, and current product behavior.
- Report conflicts, missing acceptance criteria, or stale status before editing.
- Build and verify only the approved scope.
- Summarize changed files, checks, remaining risks, and any acceptance criterion that is still open.
- Request approval before changing Linear, then re-read the issue to confirm the result.
Practical prompts for Linear and Codex
Plan a task: Read ENG-123 and its linked issues. Compare the acceptance criteria with the repository. Produce a scoped implementation plan. Leave code and Linear unchanged. List contradictions and open questions.
Investigate a bug: Read BUG-42, including reproduction steps and relevant comments. Inspect the related code and tests. Explain the likely cause with evidence. Wait for a separate request before implementing a fix.
Implement approved work: Use ENG-123 as the scope ledger. Implement its accepted criteria, run the relevant checks, and report any unmet criterion. Keep the issue state and comments unchanged.
Prepare an update: Compare ENG-123 with the verified repository state. Draft a concise Linear comment that lists completed work, checks, and remaining risk. Show the comment before posting it.
See Merge's issue-context examples for an alternative managed integration workflow.
Keep Linear writes safe
Treat creating, editing, moving, assigning, labeling, commenting, and archiving as external writes. A clear prompt should name the allowed object, fields, and action. It should also name forbidden actions.
- Use read-only access for discovery, planning, summaries, and audits.
- Require a preview before bulk creation, state changes, assignments, or comments.
- Keep OAuth tokens and API keys out of repositories, prompts, issues, and logs.
- Limit tools and scopes to the current role and workflow.
- Use exact issue identifiers and verify the workspace before each write.
- Re-read changed objects and report the resulting identifiers, fields, and states.
- Let people approve priorities, scope, destructive actions, and final workflow states.
Apply Better Design's AI guardrails when an agent can change project records.
Troubleshoot Linear MCP in Codex
The server does not appear
Run codex mcp list and inspect the active config.toml. Restart the desktop app or IDE extension after changes. For project configuration, confirm that the project is trusted. Remove duplicate server names that point to different endpoints.
Authentication fails or expires
Run codex mcp login linear again and complete OAuth with the intended Linear account. Check browser redirects and workspace access. Avoid replacing OAuth with a broad personal API key merely to bypass a fixable login problem.
Codex reads the wrong workspace
Sign out of the server, authenticate the correct account, and test a known issue identifier. Teams using multiple workspaces should keep authentication contexts separate and name servers clearly. Confirm the workspace instead of relying on an ambiguous issue title.
An older guide uses the SSE endpoint
Linear now identifies /mcp as the primary Streamable HTTP endpoint. Its /sse endpoint is a deprecated fallback for clients without Streamable HTTP support. Use current official setup instructions for new connections.
A tool is missing or blocked
Check the chosen endpoint, OAuth scope, enabled_tools, disabled_tools, and approval settings. Read-only connections intentionally omit write tools. A workspace role can also limit access. Expand permissions only for a clearly defined action.
Direct Linear MCP or an integration platform?
The direct Linear server is the shortest route for Linear-only work and has official setup guidance. Integration platforms can combine Linear with many services, centralize governance, or provide different tool surfaces. Compare data paths, permissions, audit needs, pricing, maintenance, and portability.
Review Composio's Codex integration when a managed multi-app router fits the workflow.
Compare Tembo's broader Codex MCP setup and configuration coverage.
Frequently asked questions
Yes. OpenAI documents MCP support in the desktop app, CLI, and IDE extension. They share configuration for the same Codex host. Open the app's MCP settings and restart after adding a server.
It can use write tools exposed by the standard endpoint when the account and scope allow them. Keep write approvals human-controlled and verify every changed object afterward.
No. The normal hosted setup uses OAuth. Linear also supports bearer tokens and API keys for specific cases, but secrets require careful storage and limited permissions.
Use read-only access when Codex only needs requirements, planning context, status, relations, or summaries. Switch to narrowly controlled write access only for a defined external action.