How to connect an agent to the Linear MCP server

The Model Context Protocol (MCP) server provides a standardized interface that allows any compatible AI model or agent to access your Linear data. The server is centrally hosted and managed. Tools are available for finding, creating, and updating objects such as issues, projects, and comments, and Linear says more functionality is on the way.

Connect natively in Claude, Cursor, and other clients, or use the mcp-remote module for clients that do not support remote MCP. Streamable HTTP is the primary transport. The interactive setup flow uses OAuth 2.1 with dynamic client registration. You can also authenticate directly with a bearer token or a Linear API key.

Choose read-write or read-only

Read-write access is the default, at https://mcp.linear.app/mcp.

For read-only access, Linear documents two options:

Connect to https://mcp.linear.app/mcp/readonly, which only ever exposes read tools.
Use the standard /mcp endpoint, but only request the read OAuth scope. Clients that request read are granted read-only access, and the underlying token cannot reach write APIs.

If you authenticate with your own API key, the FAQ describes a further read-only approach: create a Linear API key with only the Read permission enabled.

The client commands on the page use https://mcp.linear.app/mcp. The readonly URL is documented as its own connection target, not inside those commands. The read scope is the other documented way to keep the standard endpoint from writing.

For new setups, use the Streamable HTTP endpoint. The SSE endpoint at https://mcp.linear.app/sse is a deprecated fallback for clients that do not support Streamable HTTP.

Claude Code

Linear's command names the server linear-server:

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Open a Claude Code session and run /mcp to go through the authentication flow.

On Claude.ai, Team and Enterprise accounts connect Linear from the connectors page. On Claude desktop, Free and Pro plans add the Linear connector from settings, under Connectors. If you use Okta, configure SAML for Linear using Okta's OIN first, then enable MCP enterprise managed authentication at the bottom of the Okta identity provider settings in Linear and paste the authorization server Issuer URI. The placeholder on the page is e.g. https://your-org.okta.com. Linear says this lets supported external MCP clients such as Claude authenticate users with your Okta-managed access policies.

Codex

Setup is the same for the IDE extension and the CLI, because the configuration is shared.

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

That prompts you to log in with your Linear account and connect it to Codex. This server name is linear, not linear-server.

If this is the first time you are using an MCP in Codex, you will need to enable the rmcp feature for this to work. Add the following to ~/.codex/config.toml:

[features]
experimental_use_rmcp_client = true

Linear also documents editing that file directly. Add:

[features]
experimental_use_rmcp_client = true

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

Then run codex mcp login linear to move through the authentication flow.

Cursor

Linear does not print a terminal command for Cursor. Install from the link on the MCP docs page, or search for Linear from Cursor's MCP tools page.

Visual Studio Code

Open the command palette. Linear shows the shortcut as CTRL/CMD P. Search for MCP: Add Server.
Select Command (stdio).
Enter npx mcp-remote https://mcp.linear.app/mcp and hit enter.
Enter the name Linear and hit enter.
Activate the server using MCP: List Servers, select Linear, and select Start Server.

Or use the documented config:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
    }
  }
}

Windsurf, Zed, fx, and other clients

Linear's generic settings are command npx, arguments -y mcp-remote https://mcp.linear.app/mcp, and environment None. The page says hundreds of other tools can use those settings. Dedicated setup pages also exist for Claude, Cursor, VS Code, Windsurf, and Zed; the snippets here are the ones printed on the MCP server page.

Windsurf uses the same mcpServers block as the VS Code config above. Open settings with CTRL/CMD comma, scroll to Cascade, then MCP servers, and choose Add Server, then Add custom server.

Zed uses a different key. Open settings with CMD comma and add:

{
  "context_servers": {
    "linear": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"],
      "env": {}
    }
  }
}

In fx, add the server and log in:

/mcp add linear https://mcp.linear.app/mcp

/mcp login linear

Follow the browser prompts to authorize access to Linear. v0 installs Linear from its connections page.

Tokens, a second workspace, and a failed connect

The server accepts an OAuth token or API key in the Authorization: Bearer <yourtoken> header instead of the interactive flow. You can use that to interact as an app user, to provide read-only access through a restricted API key, or to integrate with an existing Linear OAuth application without an extra authentication hop.

The server authenticates each session via OAuth. Reconnecting alone does not switch the workspace within an existing auth session, so each workspace needs its own authentication context. If your client or mcp-remote supports a configuration directory, Linear's example is MCP_REMOTE_CONFIG_DIR:

MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/workspace-a npx mcp-remote https://mcp.linear.app/mcp
MCP_REMOTE_CONFIG_DIR=~/.mcp-auth/workspace-b npx mcp-remote https://mcp.linear.app/mcp

Authenticate each configuration separately. For clients that manage their own auth storage, check that client's documentation for workspace-switching options.

If you see an internal server error while connecting, clear saved auth and try again:

rm -rf ~/.mcp-auth

You may also need a newer version of Node. The FAQ does not name which version.

If a remote connection drops or is not responding, disconnect and reconnect the server from the client's MCP settings. Linear calls this a routine client-side reset. It does not affect your Linear data or authentication session.

On WSL, if the default Streamable HTTP endpoint does not work, use the SSE fallback Linear prints. The /sse path is legacy, for clients that do not support Streamable HTTP:

{"mcpServers": {"linear": {"command": "wsl","args": ["npx","-y","mcp-remote","https://mcp.linear.app/sse","--transport sse-only"]}}}

What to do after authentication

The same page has example prompts for roadmap planning, standup note automation, incoming bug investigation, team cycle summarization, timeline generation, and an implementation plan. Several of those prompts tell the agent to show the proposed project, comments, or issue breakdown before anything is written.

Next step: add the server in the client you use and finish its authentication flow. If the agent should not write, connect to https://mcp.linear.app/mcp/readonly or request only the read scope before you paste a prompt that creates or updates issues. Then open the example prompts on Linear's MCP docs and start with a lookup or a summary.

Sources

MCP server