Jun 23, 2026

Linear MCP vs Linear API - Right Choice for AI Agents?

TL;DR

Linear's official MCP server covers issue, comment, project, milestone, initiative, and project-update operations plus documentation search. Webhooks, arbitrary GraphQL field selection, OAuth application management, and high-volume complexity-controlled queries are absent from the MCP surface and live only in the GraphQL API.
Linear MCP authenticates with OAuth 2.1 plus Dynamic Client Registration, and it also accepts a Linear API key or OAuth token passed in the ^{Authorization: Bearer} header. The GraphQL API adds personal API keys, the ^{Authorization Code} flow with PKCE, and the ^{Client Credentials} grant for app actor (service account) tokens.
Unlike most vendor MCP servers, Linear's is not OAuth-only. A headless agent can drive it with a minted app actor token, so the hard headless blocker that exists for Salesforce or Notion MCP does not apply here.
For multi-tenant B2B agents, both paths still produce one credential per user. Neither stores, rotates, or revokes it for you. That is infrastructure regardless of which path you choose.
Scalekit's Linear connector resolves the per-user token on every call, exposes both scoped tools and a ^{linear_graphql_query} escape hatch plus webhook management, and keeps a 90-day audit trail, so the MCP vs API decision does not change your auth infrastructure.

Your agent needs to read and write Linear. Linear ships a hosted MCP server at https://mcp.linear.app/mcp and a full GraphQL API at https://api.linear.app/graphql. They are not the same surface: different capability coverage, different auth paths, different operational load in production. The choice is also not permanent. What your agent does in Linear decides which path fits. Here is how to pick.

What Linear MCP and Linear API actually are

Linear MCP

Linear's hosted MCP server launched in May 2025, built with Cloudflare and Anthropic, and is maintained by Linear directly. It runs as a remote, centrally managed server at https://mcp.linear.app/mcp over Streamable HTTP; the older /sse transport is being removed.

The default connection path is OAuth 2.1 with Dynamic Client Registration: the user authorizes in a browser, and the server routes tool calls against Linear on the agent's behalf. The server also accepts a Linear API key or OAuth token passed directly in the Authorization: Bearer header, which lets you connect as an app user or with a restricted read-only key without the interactive hop.

Its tools cover finding, creating, and updating issues, comments, projects, project updates, milestones, initiatives, initiative updates, and labels, plus documentation search and image loading.

Official docs: linear.app/docs/mcp.

Linear API

The Linear API is GraphQL, not REST, at https://api.linear.app/graphql. It is the same API Linear uses internally, it supports introspection, and it exposes the full workspace surface: issues, comments, projects, cycles, initiatives, documents, labels, workflow states, users, teams, webhooks, and OAuth application management.

Authentication accepts personal API keys (Authorization: <key>, no Bearer, scopable to Read, Write, Admin, Create issues, or Create comments, and limited to specific teams), OAuth 2.0 Authorization Code with PKCE, and the Client Credentials grant for app actor tokens used in server-to-server work.

Official docs: linear.app/developers/graphql.

Comparing them where it matters for agents

What your agent can actually do

The MCP server covers the conversational and project-management core well. The GraphQL API owns the operational, event-driven, and administrative surface.

Capability

Linear MCP (official)

Linear GraphQL API

Search issues

Yes

Read, create, update issues

Yes

Comments

Yes

Projects and project updates

Yes

Project milestones

Yes

Initiatives and initiative updates

Yes (added Feb 2026)

Yes

Labels

Yes

Documentation search

Yes

Not applicable

Arbitrary field selection and nested queries

No (fixed tools)

Yes

Webhook creation and management

Yes

Real-time change events

Yes (webhooks)

OAuth application management

Yes

Member API key governance

Yes

High-volume pagination with complexity control

Limited

Yes

Where the gap bites

The MCP surface is a fixed, evolving set of tools shaped for LLM consumption. The GraphQL API is the whole schema, queryable field by field. If your agent needs to react to a Linear change, monitor a workspace at volume, manage OAuth applications, or select exactly the fields it wants in one round trip, those capabilities are GraphQL-only. They are not missing MCP tools that ship next month; webhooks and schema-level querying are architectural properties of the API.

The auth path each one puts you on

MCP: OAuth 2.1, plus a bearer escape hatch

The default MCP path is OAuth 2.1 with Dynamic Client Registration. Every user authorizes in a browser, and the resulting session is scoped to that user's Linear permissions. The important nuance: Linear's MCP server also accepts an API key or OAuth token in the Authorization: Bearer header, so you are not locked into the interactive flow.

API: four credential models

The GraphQL API supports personal API keys (static, user-scoped, scope-limited, team-limited), the Authorization Code flow with PKCE for per-user delegation, the Client Credentials grant for app actor tokens with no user in the loop, and Actor Authorization (actor=app) so mutations appear as the app rather than the user. Per-user delegation and headless service identity both work natively.

The headless story is softer here

For most vendors, MCP being OAuth-only is a hard blocker for background agents. Linear is different. Because the MCP server accepts a bearer token, a scheduled or background agent can mint an app actor token through the API's Client Credentials grant and drive the MCP server with it. The decision becomes a tradeoff about capability and control, not a wall.

The identity problem that follows you either way

For a multi-tenant B2B agent, every workspace member who authorizes the agent produces one credential. MCP's OAuth flow gives you a token per user. The API gives you a credential per user as well. Neither path solves storage, rotation, or revocation; that is infrastructure you own regardless of which path you took.

What you own in production

On the MCP path

Linear manages the server, the tool schemas, and endpoint normalization. When Linear updates its API, the MCP tools pick up changes without a redeploy on your side. What you still own: per-user token storage, refresh, revocation on disconnect, and tenant isolation. MCP tool schemas are unversioned and can change when Linear updates the hosted server.

On the API path

You own the full stack: query construction, pagination, error handling, retries, and the token lifecycle. GraphQL gives you a single evolving schema rather than versioned REST endpoints, which means you migrate as the schema evolves rather than pinning a version. For deterministic pipelines, that single-schema model is predictable, and you decide exactly what each call fetches.

Rate limits hit the same backend

API key authentication allows up to 5,000 requests per hour and 3,000,000 complexity points per hour, shared per user across keys, with a single-query ceiling of 10,000 complexity points. OAuth apps using Actor Authorization get limits scaled by the number of paid users in the workspace. MCP tool calls consume the same complexity budget, because they resolve against the same GraphQL backend. Plan capacity from day one on either path.

When to use MCP, when to use the API

Use Linear MCP when

Your agent is interactive and developer-facing: Claude Code, Cursor, Codex, or an assistant where the user is present for OAuth consent.
The core job is reading, searching, triaging, and updating issues, projects, and cycles in natural language.
You want Linear to maintain the tool schemas and you do not want to write GraphQL.
You are prototyping and want a working Linear agent quickly with LLM-native tool descriptions.

Use the Linear GraphQL API when

Your agent must react to Linear changes through webhooks, which the MCP server does not expose.
You need arbitrary field selection, deep nested queries, or complexity-controlled pagination over large datasets.
You need administrative operations: OAuth application management or member API key governance.
You are building a deterministic pipeline and want to control exactly what each call fetches and how schema changes land.

What the tool surfaces actually expose

Read the official tool surface before you commit

The fastest way to avoid a mid-build surprise is to compare both surfaces from primary sources rather than assuming parity. The Linear MCP tool surface is documented at linear.app/docs/mcp and expanded through the Linear changelog; the full GraphQL schema is introspectable at https://api.linear.app/graphql and documented at linear.app/developers.

What the MCP server cannot do that the API can

Webhook management and real-time event delivery are API-only. Arbitrary GraphQL field selection is API-only; the MCP tools return fixed shapes, so an agent that needs one specific field still pulls a tool's whole response. OAuth application management and member API key governance are administrative operations that the MCP surface does not expose at all.

What the MCP server makes easier than the API

Tool discovery and schema handling come for free on the MCP path: the agent receives LLM-ready tool descriptions instead of an introspected GraphQL schema it has to map to functions. Documentation search and image loading are MCP conveniences with no direct single-call API equivalent. For an interactive assistant, that lower setup cost is the whole point.

The credential problem that exists on both paths

One token per user, on either path

Whether you chose MCP or GraphQL, every user in your multi-tenant agent has their own Linear credential. Fifty customers means fifty tokens and fifty lifecycles. The MCP OAuth flow gives you a session-scoped token per user; the API's OAuth flow gives you an access token per user. The token type differs; the management burden does not.

What neither path gives you

Neither path provides a vault, rotation logic, or a revocation flow. Tokens still need to be encrypted at rest, isolated per tenant, and revocable when a user disconnects. When a user revokes access inside Linear, your agent has no built-in signal; it learns by catching the failure and either refreshing or re-prompting. That detection and recovery is yours to build. This is the same credential ownership challenge that appears across every agent tool-calling pattern.

Where Scalekit fits

Scalekit's Linear connector resolves the per-user token on every tool call, so issue assignments, status changes, and comments carry the right identity and a full audit trail tied to the user who authorized them, not a shared bot account. The same auth layer works whether you went MCP or GraphQL, so the path decision does not change what you need at the credential layer.

Building on Linear with Scalekit

The value proposition for a Linear agent

Linear is where fast engineering teams live, so a Linear agent is usually multi-user and often multi-tenant from day one. That is exactly where shared credentials fail: a shared token logs every action as the integration, which breaks per-engineer workload metrics and team attribution. Scalekit's connector acts as the user, keeps credentials in an AES-256 token vault resolved at request time in roughly 40 milliseconds, and never places a token in the LLM context.

You keep the MCP convenience and recover the API surface

Scalekit's Linear connector is broader than the official MCP surface. Alongside scoped tools like linear_issues_list, linear_issue_search, and linear_issue_create, it ships linear_webhook_create, linear_webhook_update, and linear_webhooks_list, plus a linear_graphql_query tool that runs any valid GraphQL operation. You get per-user scoping and the API-only capabilities the official MCP drops, in one connector. Browse the tools at the Scalekit Linear connector and the connector docs.

Authorize a user and make your first call (Node.js)

The agent receives only the tools the current user's connected account authorizes, never a flat catalog. Authorize once per user, then call execute_tool.

import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENV_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'linear' // must match the connection name in your Scalekit dashboard const identifier = 'user_123' // Generate a per-user authorization link const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Linear:', link) // After the user authorizes, run a scoped tool call const result = await actions.executeTool({ connector, identifier, toolName: 'linear_issues_list', toolInput: {}, }) console.log(result)

The same flow in Python

The connection_name must match the connection configured in your Scalekit dashboard; a mismatch here is the most common integration error.

import os from scalekit.client import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENV_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "linear" # must match the connection name in your Scalekit dashboard identifier = "user_123" # Generate a per-user authorization link link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Linear:", link_response.link) # After the user authorizes, run a scoped tool call result = actions.execute_tool( tool_input={}, tool_name="linear_issues_list", connection_name=connection_name, identifier=identifier, ) print(result)

Wiring scoped Linear tools into LangChain

listScopedTools returns the surface authorized for the current connected account, not a connector catalog. Filtering to a handful of tools keeps the decision space small, which is the lever for tool-calling accuracy.

import { ScalekitClient } from "@scalekit-sdk/node"; import { DynamicStructuredTool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { z } from "zod"; const sk = new ScalekitClient(envUrl, clientId, clientSecret); const { tools } = await sk.tools.listScopedTools("user_123", { filter: { connectionNames: ["linear"], toolNames: ["linear_issues_list", "linear_issue_search", "linear_issue_create"] }, pageSize: 100, }); const lcTools = tools.map((t) => new DynamicStructuredTool({ name: t.tool.definition.name, description: t.tool.definition.description, schema: z.object({}).passthrough(), func: async (args) => { const { data } = await sk.tools.executeTool({ toolName: t.tool.definition.name, identifier: "user_123", params: args, }); return JSON.stringify(data); }, })); const agent = createReactAgent({ llm, tools: lcTools });

Calling Linear tools from Claude

The same scoped surface maps directly onto Anthropic's tool format.

import { ScalekitClient } from "@scalekit-sdk/node"; import Anthropic from "@anthropic-ai/sdk"; const sk = new ScalekitClient(envUrl, clientId, clientSecret); const anthropic = new Anthropic(); const { tools } = await sk.tools.listScopedTools("user_123", { filter: { connectionNames: ["linear"], toolNames: ["linear_issues_list", "linear_issue_search", "linear_issue_create"] }, pageSize: 100, }); const llmTools = tools.map((t) => ({ name: t.tool.definition.name, description: t.tool.definition.description, input_schema: t.tool.definition.input_schema, })); const msg = await anthropic.messages.create({ model: "claude-sonnet-4-6", max_tokens: 1024, tools: llmTools, messages: [{ role: "user", content: prompt }], });

The GraphQL escape hatch, still scoped per user

When you need a field the scoped tools do not return, call linear_graphql_query. It runs any valid GraphQL operation under the same per-user credential, so you get the full schema without dropping out of the vaulted, audited path.

result = actions.execute_tool( connection_name='linear', identifier='user_123', tool_name='linear_graphql_query', tool_input={ "query": "{ viewer { id name email } }", }, ) print(result)

Virtual MCP for clients that speak MCP

If your runtime expects an MCP endpoint, Scalekit gives every agent a scoped, user-specific Virtual MCP endpoint, authorized with a short-lived per-user token. One server definition serves all users; the endpoint is static and the identity is per-user. There is no MCP server for you to deploy, host, or maintain.

Observability for multi-tool and multi-tenant agents

Every Linear tool call is logged with who triggered it, which resource was touched, and what came back, retained for 90 days and exportable to your SIEM. For a multi-tenant agent, that audit chain is the difference between answering a security questionnaire and stalling on it. Adding the next connector inherits the same vault, audit chain, and delegation pattern, so a Linear agent extends to GitHub, GitLab, Jira, or Slack without new auth code per tool.

Need event-driven Linear that is not in your stack yet

If you need a specific Linear capability that is not yet wired the way you want, for example native webhook receipt routed into your agent runtime, request it. Join the Scalekit Slack community or talk to us and we will scope it with you.

Which one to build against

If your agent is interactive and developer-facing and its job is searching, triaging, and updating Linear in natural language, the MCP server is the faster route to a working agent. If your agent must react to Linear changes through webhooks, run administrative operations, or select exact fields at volume, build against the GraphQL API directly. Most production Linear agents end up using both: MCP for the interactive surface, GraphQL for the event-driven and operational work. The credential management problem is identical either way, and that is the part that needs production-grade infrastructure.

Next: Browse the Scalekit Linear connector.

No items found.

On this page

Introduction
‍

This is some text inside of a div block.