How to connect to the Linear MCP with Claude Code (5 steps)

This guide walks through connecting AI agents to Merge Agent Handler's Linear MCP server via Claude Code. 

Once set up, your Claude agents can create issues, update statuses, manage projects, and search across your Linear workspace without leaving the terminal.

Prerequisites   

• A Merge Agent Handler account
• Claude Code installed and configured
• A Linear account with sufficient workspace permissions
• A Tool Pack in Merge Agent Handler with the Linear connector enabled                                                                                                                                             
• A Registered User in Merge Agent Handler
• An API key from Merge Agent Handler

How it works

Merge Agent Handler acts as a secure bridge between your agent and Linear's API. 

You’ll need to configure a Tool Pack (a collection of connectors with scoped permissions) and a Registered User (the identity your agent operates under). 

Those two items produce a unique MCP URL. And Claude Code connects to that URL over HTTP, making Linear's tools available as native functions in your terminal session.

Related: A guide to connecting to Slack MCP with Claude Code

Steps for connecting to Linear’s MCP through Claude Code

You’ll need to use the following code to connect to the Linear MCP server:

{
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

You can get the custom items (i.e., your MCP URL and auth token) by taking the following steps:

1. Create a Tool Pack      

Log into the Merge Agent Handler dashboard, go to Tool Packs, and click Create Tool Pack. Give it a name like "Engineering Agent", a description, and select Linear as the connector.   

  2. Add a Registered User   

Navigate to Registered Users and click Add Registered User. 

This creates the identity context your agent operates under. Merge generates a unique MCP URL once the user is created.          

3. Authenticate Linear

From the Registered User detail page, click Add Connector and complete the Linear OAuth flow. This grants your agent access to the Linear workspace.          

  4. Grab your credentials 

From the Merge Agent Handler dashboard, collect: 

• Your MCP URL (found on the Tool Pack detail page under the Registered User). It should look like this (with the Tool Pack ID and Registered User ID populated):

<code class="blog_inline-code">https://ah-api.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp</code>

• An API key (Settings > API Keys > Create new key) 

5. Configure Claude Code

Run this in your terminal (with your own API key and MCP URL):

  Confirm it connected by entering <code class="blog_inline-code">claude mcp list</code>.       

You should see agent-handler listed with a connected status. 

{{this-blog-only-cta}}

Linear MCP FAQ 

In case you have any more questions on setting up and using a Linear MCP server in Claude Code, we’ve addressed several more questions below:

What can your agent do with a Linear MCP server?

Here are just a few common use cases:

• Create and update issues: Quickly log new bugs/feature requests and keep them current by updating titles, descriptions, priority, labels, and due dates as work evolves

• Assign issues to team members: Route work to the right owner (or reassign as priorities shift) so accountability and handoffs stay clear

• Move issues through status workflows: Keep execution in sync by transitioning issues across your team’s workflow states (e.g., Triage → In Progress → In Review → Done) as progress happens

• Search issues by project, label, or assignee: Pull up exactly the set of issues you need (e.g., “all P0 bugs in Project X assigned to the on-call”) to unblock planning and execution

• Retrieve cycle (sprint) progress: Summarize what’s on track vs. at risk by checking cycle scope, completed work, and remaining issues at any point in the sprint

• Create and manage projects: Set up projects, update milestones/timelines, and maintain project status so the roadmap reflects reality without manual upkeep

Why should I use Merge Agent Handler's Linear MCP server?

Using the connector’s 30+ tools, your agents can operate autonomously across the entire project management lifecycle. 

Here’s additional context:

• Full issue lifecycle: Not just <code class="blog_inline-code">get_issues</code> but create, update, archive, filter by identifier, and paginate. Agents can triage, reassign, reprioritize, and close issues without human intervention    

• ‍Project updates are unique: Linear's project update feature (health status, progress notes) is specific to Linear and often overlooked. The connector supports create, update, archive, and unarchive on project updates, meaning agents can automate weekly status reporting

• Cycle support: Agents can read sprint data via <code class="blog_inline-code">list_cycles</code>, which opens up use cases like summarizing sprint progress or flagging overdue issues mid-cycle

• Comment resolution: <code class="blog_inline-code">resolve_comment</code> and <code class="blog_inline-code">unresolve_comment</code> mirror a workflow that engineering teams actually use to track whether feedback was addressed

• Team management: <code class="blog_inline-code">create_team</code> and <code class="blog_inline-code">update_team</code> means agents can do onboarding automation, not just day-to-day task management   

Why should I connect to a Linear MCP server with Claude Code?

In simple terms, Linear is where engineering work lives, and Claude Code is where engineers already are. So connecting them means your agent can act on your backlog without your engineers switching contexts.