Linear MCP Deep Dive 2026 — Official Remote Server, OAuth 2.1 + DCR, 25+ Tools, and 7 GraphQL Pitfalls

Why Linear MCP is one of 2026's standout integrations

Linear is a modern project management tool for software teams — issues, cycles, projects, roadmaps, all operated through a famously fast, keyboard-first UX. From late 2025 into 2026, Linear has rolled out an official MCP server co-designed with Cloudflare and Anthropic, becoming a reference implementation for the agent era of project management.

In KanseiLink's dataset, Linear's official MCP is graded connectable with a trust score of 0.7 — a remote-hosted, OAuth 2.1-authorized server exposing 25+ tools. The most important architectural choice is "no local process, just a URL" — while most MCP servers still rely on npx-launched stdio processes, Linear is clearly a step ahead.

Architecture — the case for remote-hosted MCP

Linear MCP is hosted at mcp.linear.app/mcp and operated by Linear themselves. Client configuration is roughly:

// MCP client config (Claude Desktop / Cursor / etc.)
{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/mcp",
      "transport": "http"
    }
  }
}

On first connection, the agent opens a browser, the user logs in to Linear and approves scopes, and the OAuth 2.1 flow returns a token that the client refreshes automatically thereafter. No API keys to issue, store, or rotate. And when Linear adds new tools, they appear without any client-side update.

Authentication pitfalls — the Bearer trap and DCR

Linear supports two auth methods: a Personal API Key (PAT) and OAuth 2.0/2.1. The MCP server prefers OAuth 2.1 + DCR, but personal scripts and service accounts often use PATs. That's where the most common bug lives.

Dynamic Client Registration (DCR)

DCR support, added in late 2025, is a meaningful upgrade for agent operations. Previously, each user had to manually register an OAuth app, generate Client ID/Secret pairs, and configure callback URLs. With DCR, the MCP client dynamically registers its OAuth client on first connection, leaving the user with one step: "log in and approve scopes."

On April 9, 2026, Linear announced a fix for a bug where MCP OAuth connections could disconnect after roughly 24 hours. The root cause was that the automatic token-refresh flow wasn't working for certain client implementations — long-running agents would simply fail the next day. The bug is fixed, but long-session agents should still implement a fallback that re-initiates the OAuth flow on auth errors.

GraphQL-only access and complexity-based rate limits

Linear exposes https://api.linear.app/graphql only — there is no REST API. Every call is POST /graphql with a query or mutation in the body.

POST https://api.linear.app/graphql
Authorization: lin_api_xxxxx          # PAT (no Bearer)
Content-Type: application/json

{
  "query": "{ viewer { id name email } issues(first: 5) { nodes { id identifier title state { name } } } }"
}

Rate limiting uses a complexity-point budget, not a requests-per-minute counter. Personal API Keys get 1,500 points/hour; OAuth apps get 5,000 points/hour. Each field and mutation has a weight, and deeply nested queries burn budget fast.

The operating rule is "minimum fields" — only query the fields the agent actually needs. GraphQL's whole point is selective fetching; if you over-select, Linear's rate limiter will bite you.

25+ tools — Initiatives, Milestones, Project Updates

Linear's February 2026 update expanded the MCP server with initiatives, project milestones, project updates, project labels, and image loading. This pushed the surface beyond pure issue management into product planning and stakeholder reporting territory.

• Issue ops: create, search, update, comment, transition states
• Cycle / sprint: get current cycle, assign issues
• Project & Initiative: create/update projects and parent initiatives
• Project Milestones: milestone lifecycle
• Project Updates: stakeholder-facing status updates
• Labels & Custom Fields: label management, project labels
• Team Management: list teams, verify memberships

7 pitfalls in agent development

❌ 1. Mixing PAT and OAuth header conventions

No "Bearer" for PATs; "Bearer" for OAuth. Watch your MCP client's auto-Bearer behaviour.

❌ 2. Unscoped issue searches

A workspace with thousands of issues bloats the response and burns tokens. Always scope by teamId when listing.

❌ 3. Deeply nested queries blow up the complexity budget

Patterns like issues { nodes { comments { nodes { user { teams { ... } } } } } } consume points fast. Flatten the query or split into two calls.

❌ 4. Confusing UUIDs and issue identifiers (ENG-42)

For human-facing flows use ENG-42-style identifiers; the API also accepts UUIDs. Normalize how the agent maps user input to API identifiers.

❌ 5. Polling for changes

A "poll issues every 5 seconds" pattern is the worst case. Use webhooks or GraphQL subscriptions (WebSocket) for push-based updates.

❌ 6. Long-session OAuth surprise failures

April's disconnect bug is fixed, but always implement an auth-error fallback that re-runs the OAuth flow.

❌ 7. Ignoring GraphQL error envelopes

Linear returns standard GraphQL errors: {"errors": [{"message": "...", "extensions": {"code": "...", "type": "..."}}], "data": null}. HTTP 200 with data: null is still a failure — always check the errors array.

Comparison with Backlog, Asana, Jira

Linear's edge is the OAuth 2.1 + DCR + remote-hosted architecture, plus the pace of new tool additions. Backlog wins on real-world agent track record — 90% success rate, 128ms average latency, 91 logged uses in KanseiLink — and currently holds AAA grade. A reasonable split: Linear for new greenfield/global-team work, Backlog for proven Japanese-market deployments.

Production-readiness checklist

• Verified your MCP client's auto-Bearer behaviour for the Authorization header
• Confirmed OAuth 2.1 + DCR flow completes on first connect
• Implemented an auth-error fallback that re-runs the OAuth flow
• Scope queries with teamId instead of listing all issues
• Apply the minimum-fields principle to every GraphQL query
• Logging/monitoring includes X-Complexity and X-RateLimit-Remaining
• Replaced polling with webhooks or GraphQL subscriptions
• Parse the GraphQL errors array — HTTP 200 doesn't mean success
• Normalize identifier (ENG-42) and UUID handling in agent input parsing
• For PATs, you have a key-rotation runbook

FAQ

Q1. Can I self-host Linear's MCP server?

The official version is remote-hosted only (mcp.linear.app/mcp). A community npm @linear/mcp-server stdio variant exists, but Anthropic/Cloudflare-aligned features (DCR, etc.) land first on the official remote. For new builds, prefer the official remote unless you have specific reasons to self-host.

Q2. How do I avoid the PAT "Bearer trap"?

Either branch your MCP client's header logic by auth method, or commit to OAuth-only. For production agents, OAuth 2.1 + DCR is the recommended path.

Q3. How do I estimate GraphQL query complexity?

Linear doesn't publish per-field weights, but X-Complexity response headers let you measure directly. Run representative production queries against staging and aggregate the headers. Anything that exceeds ~100 per call deserves a rewrite.

Q4. When to use webhooks vs. subscriptions?

Webhooks are HTTP POSTs to your external endpoint; subscriptions push directly to a connected client over WebSocket. Server-side agents typically prefer webhooks; interactive client-side agents prefer subscriptions.

Q5. Why isn't Linear graded AAA on KanseiLink yet?

As of May 2026, the usage_count metric is still 0 — KanseiLink hasn't accumulated enough real-world agent reports. The MCP is recent and the technical quality is high; once usage data builds up, an upgrade to AAA is plausible. Deep dives like this one help accelerate that signal.

Q6. Should Japanese teams move from Backlog to Linear?

It depends. Linear excels at developer experience, GitHub integration, and speed. Backlog wins on Japanese UI, non-engineer accessibility (sales/PM/CS), and domestic legal compliance (electronic books law, etc.). Pure engineering teams: Linear. Mixed-role organizations: Backlog.