Linear is the issue tracker of choice for fast-moving engineering teams. But when AI agents enter the workflow, a gap emerges: your agent can write code, but it has no idea what tickets exist, what sprint you are in, or which issues are blocked. A Linear MCP server bridges that gap by giving agents structured access to your issue tracker — read issues, create sub-tasks, update status, and pull sprint context — all through the Model Context Protocol.
What a Linear MCP Server Provides
A Linear MCP server exposes your Linear workspace as a set of tools that AI agents call over JSON-RPC. The agent can list issues in the current sprint, read full issue details including comments and attachments, search issues by keyword or label, create new issues and sub-issues, update issue status and assignee, and read team and project metadata. These tools transform your agent from a code-only assistant into a project-aware collaborator.
The practical impact is significant. Instead of telling your agent 'build the user settings page' and hoping it guesses the requirements, you say 'implement LIN-342.' The agent calls the Linear MCP server, reads the full issue description, checks linked issues for additional context, reads comments where the team discussed edge cases, and starts building with complete requirements context. When it finishes, it updates the issue status and links the PR.
How It Works Under the Hood
Linear's MCP integration uses the same protocol as every other MCP server: JSON-RPC 2.0 over Streamable HTTP. The server authenticates against Linear's API using an OAuth token or API key, translates MCP tool calls into Linear GraphQL queries, and returns structured JSON responses. The agent discovers available tools during the MCP handshake and calls them as needed.
The authentication flow supports both personal API keys (for individual use) and OAuth apps (for team-wide deployment). OAuth is preferred for production setups because tokens can be scoped to specific workspaces and revoked centrally. The MCP server handles token refresh automatically, so agents maintain access across long coding sessions without interruption.
// .cursor/mcp.json — Linear MCP server config
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@anthropic/linear-mcp-server"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxx"
}
}
}
}
// Agent tool call example:
// linear_search_issues({ query: "user settings", status: "In Progress" })
// Returns: matching issues with full metadataWhat Agents Can Do with Linear Context
With Linear tools available, agents gain several powerful workflows. Sprint-aware development means the agent can check what is in the current cycle, pick the highest-priority unassigned issue, and start implementation. Dependency-aware planning means the agent reads blocked-by relationships and works on unblocked issues first. Ticket-linked PRs mean the agent creates pull requests that reference the Linear issue, so your team sees the connection in both Linear and GitHub.
Agents can also perform triage tasks: reading new bug reports, classifying severity based on the description and stack trace, adding labels, and assigning to the right team. For teams that receive high volumes of user-reported issues, this automated triage saves hours of manual sorting each week while ensuring consistent classification.
Linear MCP vs. AppHandoff Tickets
Linear and AppHandoff serve different layers of the development workflow. Linear is a general-purpose issue tracker for all engineering work — features, bugs, tech debt, support tickets. AppHandoff's ticket system is specifically designed for AI agent coordination: handoff tickets include architecture context (API specs, DB schemas, mismatch data), implementation plans generated from code analysis, and multi-role workflows where different agents handle different aspects of a ticket.
The key difference is context density. A Linear issue has a title, description, and comments — human-readable text that agents must interpret. An AppHandoff handoff ticket includes structured machine-readable data: the exact API endpoints involved, the database tables affected, the frontend components that need changes, and the mismatch between what exists and what is needed. This structured context lets agents start coding immediately rather than spending tokens parsing natural language requirements.
Many teams use both: Linear for overall project management and sprint planning, AppHandoff for the specific AI-to-AI and AI-to-human handoff workflow. The two systems can sync via webhooks — when an AppHandoff ticket is resolved, the linked Linear issue updates automatically.
# Linear issue (human-readable):
Title: Add user settings page
Description: Users need to update their display name and email preferences.
Labels: feature, frontend
# AppHandoff handoff ticket (machine-readable):
{
"ticket": "HO-1234",
"type": "feature",
"context": {
"api_endpoints": ["/api/v2/users/:id/settings"],
"db_tables": ["user_preferences"],
"frontend_components": ["SettingsPage", "PreferencesForm"],
"mismatches": [
{ "endpoint": "/api/v2/users/:id/settings", "issue": "missing PATCH handler" }
]
}
}Setting Up the Linear MCP Server
Setup takes under five minutes. You need a Linear API key (generate one from Linear Settings > API > Personal API keys) and an MCP-compatible editor. The community maintains several Linear MCP server packages — the most mature is the official Anthropic-maintained server, which supports the full Linear API surface including issues, projects, cycles, and team management.
For Cursor users, add the server to your .cursor/mcp.json file with the command and API key. For other editors that support MCP (VS Code with extensions, Claude Code, Windsurf), the configuration follows the same pattern — specify the server command and provide the API key as an environment variable. Once connected, your agent can immediately list issues and start working with full project context.
Practical Tips for Linear + MCP Workflows
Start by having agents read tickets before coding. The single most impactful change is adding 'read the ticket first' to your agent workflow. This sounds obvious, but most teams prompt agents with copy-pasted ticket descriptions instead of letting the agent read the source directly. When the agent reads from Linear via MCP, it gets the latest version including recent comments and status changes.
Use labels to signal agent-readiness. Create a 'mcp-ready' label in Linear for issues that have enough detail for an agent to implement. This prevents agents from picking up vague one-liner issues and generating speculative code. When triaging, apply the label only to issues with clear acceptance criteria, linked designs, and defined API contracts.
Combining Linear and AppHandoff MCP
For the most powerful agent workflow, connect both Linear and AppHandoff MCP servers to your editor. Linear provides the project management layer — what to build, in what order, with what priority. AppHandoff provides the architecture layer — how to build it, what the current code looks like, where the contracts are, what mismatches exist. Together, they give agents complete context: the 'what' from Linear and the 'how' from AppHandoff.
Learn more about setting up MCP connections in the getting started guide at /mcp-server, or see how AppHandoff works with Lovable-built frontends at /mcp-for-lovable. For a hands-on walkthrough connecting your first MCP server, the setup tutorial at /blog/how-to-set-up-mcp-with-lovable covers the full process from zero to working agent context.