Linear MCP Setup: Start Read-Only, Then Add Write Access
To set up Linear MCP safely, connect an MCP-capable client to Linear’s official read-only endpoint, https://mcp.linear.app/mcp/readonly, and complete OAuth in your browser. Confirm harmless reads such as teams, projects, or issues, then switch to https://mcp.linear.app/mcp only when the workflow requires creating, changing, or commenting in Linear.
To set up Linear MCP safely, connect an MCP-capable client to Linear’s official read-only endpoint, https://mcp.linear.app/mcp/readonly, and complete OAuth in your browser. Confirm harmless reads such as teams, projects, or issues, then switch to https://mcp.linear.app/mcp only when the workflow requires creating, changing, or commenting in Linear.
Table of contents
- What Linear MCP connects
- Choose the read-only or write-capable endpoint
- Connect Claude, Cursor, or another client
- Prove the connection with harmless reads
- Add write access without widening the blast radius
- Troubleshoot OAuth and missing tools
- FAQ
What Linear MCP connects
Linear MCP connects an MCP-capable AI client to your Linear workspace through Linear’s fully hosted remote server. Linear provides a read-only HTTP endpoint at https://mcp.linear.app/mcp/readonly and a standard endpoint at https://mcp.linear.app/mcp; both use OAuth authentication. Linear’s MCP documentation describes the official connection model.
The server exposes a curated tool surface for issues, projects, comments, cycles, documents, teams, and users. It is an abstraction over Linear’s GraphQL API rather than a one-to-one copy of every API operation, so common assistant tasks use focused tools.
You can use the connection to:
- Find issue and project context inside an editor or chat.
- Triage and file issues.
- Summarize what a team is working on.
- Draft project updates.
- Move work through a workflow.
- Leave comments when write access is authorized.
The server acts with your own Linear user permissions. You need a Linear account and workspace, an MCP client that supports remote or HTTP servers, and a browser for the OAuth 2.1 authorization flow. Any Linear plan can use the basic connection requirements.
Choose the read-only or write-capable endpoint
Linear publishes two official remote URLs: use https://mcp.linear.app/mcp/readonly when the client must not change workspace data, or https://mcp.linear.app/mcp for the standard write-capable connection. The read-only endpoint is the safest starting point for search, summaries, and workspace context.
Move to the standard endpoint only when the workflow genuinely needs to create issues, change status, or add comments. A client that supports OAuth scope selection can also request the read scope against the standard endpoint, but the dedicated read-only URL makes the boundary explicit in configuration.
| Workflow | Start with | Reason |
|---|---|---|
| Find teams, issues, projects, or users | Read access | Confirms identity and workspace context |
| Summarize cycles or project activity | Read access | Produces useful output without changing data |
| Create an issue or project update | Write access | Requires an intentional mutation |
| Move an issue or leave a comment | Write access | Changes the shared Linear workspace |
OAuth does not require an API key. For a headless client, Linear can optionally accept an API key from Settings → Security & access as an Authorization: Bearer token. Keep that option separate from the browser-based OAuth path, and preserve the same permission discipline. The MCP security best practices provide the relevant least-privilege principles.
Connect Claude, Cursor, or another client
To connect Claude, Cursor, or another supported client, add the endpoint that matches the intended boundary: https://mcp.linear.app/mcp/readonly for a read-only start, or https://mcp.linear.app/mcp when writes are required. Complete the browser OAuth flow; remote-capable clients do not require a local Linear server installation.
The supported client category includes Claude web and desktop, Claude Code, Cursor, VS Code, Codex, Windsurf, Zed, and other clients that support remote or HTTP MCP servers. For client-specific setup context, see the Claude setup guide or Cursor setup guide.
The connection sequence is:
- Open the client’s MCP or remote-server settings.
- Add the Linear MCP URL.
- Start the OAuth authorization flow.
- Select the intended Linear account and workspace.
- Approve the narrowest useful access.
- Return to the client and confirm that the server is connected.
For an editor that supports only local stdio servers, the verified fallback is a local npx mcp-remote proxy running on Node.js 18 or newer. The Linear server itself remains hosted remotely; the proxy only adapts the transport expected by that editor. MCP’s architecture guide explains how clients and servers communicate through the protocol.
Prove the connection with harmless reads
After OAuth completes, test the connection with read operations before asking the assistant to create, update, move, or comment. Start by requesting visible teams, an existing issue, or a project summary.
Use this short validation sequence:
- Ask the assistant to identify the connected Linear workspace or list available teams.
- Request an existing issue by identifier or search for a known project.
- Ask for a summary of the returned context without requesting an action.
- Compare the result with what you can see directly in Linear.
- Confirm that the assistant is using the intended account and workspace.
A successful OAuth redirect proves that authorization completed; it does not prove that every tool or write operation is available. Check the returned data for the expected team, project, issue status, and user context.
This read-first step also helps separate connection problems from permission problems. If a harmless lookup works, the transport and basic authorization are likely functioning. You can then evaluate whether a missing operation reflects client support, Linear permissions, or the MCP server’s curated tool surface. Linear’s published MCP workflows describe the kinds of product-management tasks the connection is intended to support.
Add write access without widening the blast radius
Add write access only after harmless reads work and the workflow genuinely requires a change in Linear. Keep each mutation explicit: name the target issue, project, team, or comment, and state exactly what should change.
A controlled write workflow looks like this:
- Choose one concrete task, such as creating an issue or leaving a comment.
- Identify the target team, project, or issue before changing anything.
- Limit the requested fields or text to what the task needs.
- Ask the assistant to state the intended action before it performs it.
- Confirm the result in Linear after the operation.
For example, an assistant may first find the correct project, summarize its current context, and prepare an update. Only after you approve the target and wording should it use the write-capable operation.
The server still acts under your Linear user permissions, so write access should match the account’s existing authority. If an action is unavailable, do not work around the permission boundary by weakening authentication or using unverified configuration. Recheck the selected account, workspace, and authorization instead.
Troubleshoot OAuth and missing tools
Start troubleshooting with four checks: the exact remote URL, the browser OAuth step, the client’s transport support, and the tools exposed after connection. Do not treat a missing tool as proof that the server is broken.
| Symptom | Likely area | Next check |
|---|---|---|
| OAuth does not finish | Browser or client session | Restart the remote-server connection and complete the browser flow again |
| Client rejects the server type | Transport support | Use a client that supports remote HTTP MCP, or the Node.js 18+ npx mcp-remote proxy for local stdio-only editors |
| Reads work but writes do not | Permissions or authorization | Confirm the Linear account, workspace, and approved access |
| Expected operation is missing | Curated tool surface | Check whether the task maps to a supported MCP tool rather than assuming full GraphQL coverage |
| Results show the wrong context | Account or workspace selection | Repeat OAuth with the intended Linear identity and verify a known team or issue |
If the connection fails after a configuration change, record the client, transport, endpoint, and non-sensitive error text. Never include OAuth tokens or API keys in diagnostic material. The MCP debugging guide offers a structured way to isolate client, transport, and tool issues.
For a local configuration check, the config doctor can be the next practical step. If the connection is valid but the available tools remain narrower than expected, use the official Linear MCP Server directory entry to confirm the endpoint, transport, authentication method, and prerequisites.