Linear MCP Claude Code — a setup that survives a second developer

On this page#

• What the integration actually does
• The wiring
• Linear workflow
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

A Linear MCP connection lets Claude Code call Linear’s exposed tools and retrieve issue context during an agent session. It does not turn Linear into repository truth, continuously synchronize tickets with code, or give the agent permission to make arbitrary workflow decisions.

MCP, or Model Context Protocol, is a standard interface through which an AI application can connect to external tools and data sources. In this setup, Claude Code is the MCP client, Linear provides the MCP server, and the server decides which operations are available.

| What people expect | What actually happens | |---|---| | Claude automatically understands the project backlog | Claude can retrieve Linear context when the relevant tool is called | | Ticket state always matches repository state | Linear and Git remain separate systems of record | | Every developer gets identical behavior | Configuration, authentication, repository location, and permissions still vary | | The agent can safely update any issue | It can perform only exposed operations allowed by the authenticated account | | Installing the server creates a team workflow | Installation creates connectivity; conventions create the workflow |

That distinction matters. “Read the issue, implement it, and move it to Done” contains three separate decisions: retrieving context, changing code, and changing external state. Treating them as one automatic action is the wrong default for a repository with real invariants.

The Claude Code overview explains the coding-agent side of the boundary. MCP expands the context and actions available to that agent; it does not replace repository instructions, tests, review, or ownership rules.

Photo by cottonbro studio on Pexels.

The wiring#

Use a repository-scoped MCP declaration when the integration is part of the project’s operating model. A private, machine-local setup is acceptable for evaluation, but it is not a team setup: the second developer cannot inspect, review, or reproduce it.

1. Add Linear as an HTTP MCP server#

From the repository root, add the remote server:

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

The equivalent project configuration is:

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

Keep the server name stable. Prompts, documentation, and troubleshooting instructions become needlessly ambiguous when one developer calls it linear, another uses linear-mcp, and a third relies on a global entry.

Project scope is the important choice here. The MCP architecture separates hosts, clients, and servers; it does not make configuration location irrelevant. Claude Code must still discover the project’s declaration from the repository context in which it starts.

2. Authenticate interactively#

Start Claude Code in the same repository:

claude

Then open the MCP interface:

/mcp

Select linear and complete the authentication flow. Do not paste personal credentials into the repository configuration. The shared file should describe how to reach the server, while authentication remains tied to each developer’s account and permissions.

That separation is deliberate:

Shared:
  server name
  transport
  endpoint
  expected workflow

Per developer:
  authentication
  Linear access
  local session state

Claude Code’s current command and configuration surface belongs to the official Claude Code documentation. Keep repository guidance focused on the contract your team owns instead of copying an entire tool manual that will drift.

3. Add the operating rules#

Connectivity without policy is incomplete. Add repository instructions that state when Claude may read Linear and when it may mutate it:

## Linear workflow

- Use Linear MCP to read the referenced issue before planning work.
- Treat repository code, tests, and documented invariants as authoritative.
- Do not change issue status, assignee, or description without explicit approval.
- Before proposing completion, report the issue identifier, changed files,
  and verification performed.
- If Linear is unavailable, continue only when the task is fully specified
  in the repository or prompt.

This is where most setups become fragile. Teams document the endpoint but leave the agent’s decision rights implicit. The Agent Operating Kit is the relevant next step when you need a reusable operating contract rather than another collection of prompts.

Photo by panumas nikhomkhai on Pexels.

The two things that break it#

Two failures dominate this setup: authentication is valid for the wrong human context, or Claude Code is started outside the configuration’s repository scope. Reinstalling the server does not fix either problem; identify which boundary failed first.

Authentication succeeds, but Linear operations fail#

The recognizable pattern is that the server appears in /mcp, yet a tool call returns an authorization error, cannot access the expected workspace, or cannot find an issue the developer can see elsewhere.

The fix is mechanical:

1. Open /mcp.
2. Select linear.
3. Disconnect or clear the failed authentication state.
4. Authenticate with the intended Linear account.
5. Confirm that account can access the target workspace and issue.
6. Retry a read-only request before attempting an update.

Do not solve this by sharing one developer’s token or session. MCP defines a connection architecture, not a shared identity model; the authenticated principal still determines accessible data and actions. The protocol boundary is described in the official MCP specification.

The server is missing or shows as failed to connect#

If /mcp does not list linear, or reports that it failed to connect, first check where Claude Code was launched. A project-scoped declaration is useful precisely because it belongs to a project, but that also means a session started in an unrelated directory may not discover it.

Use this recovery sequence:

cd /path/to/the/repository
claude

Then inspect:

/mcp

If the server is listed but still cannot connect, verify that the committed declaration contains the expected HTTP transport and endpoint. Do not add a second global server with the same purpose. Duplicate registrations hide the configuration error and create machine-dependent behavior.

For broader setup patterns around agent-to-tool boundaries, use the Wiring It In collection.

Verifying it works#

A green connection indicator proves only that Claude Code can see the server. Real verification requires one identifiable read, one permission-boundary check, and—only with approval—one reversible write whose result is independently visible in Linear.

Run these checks in order:

1. In /mcp, confirm that linear is connected.
2. Ask Claude to list the Linear tools available in the session.
3. Provide a known issue identifier and request a concise summary.
4. Confirm the returned identifier, title, and current state against Linear.
5. Ask Claude to describe the update it would make without executing it.
6. If external writes are allowed, approve one low-risk change explicitly.
7. Verify the resulting issue state in Linear, not only in Claude’s response.

A useful verification prompt is:

Read Linear issue <ISSUE-ID>. Return its identifier, title, current state,
and the acceptance criteria you can actually retrieve. Do not modify anything.
If any field is unavailable, say so instead of inferring it.

The last sentence is essential. An agent can produce a plausible summary from partial context; plausibility is not proof of retrieval. The client-server-tool flow in the MCP architecture documentation explains why each tool result should be treated as scoped output, not omniscient project knowledge.

Photo by Christina Morillo on Pexels.

Team considerations#

The second developer usually fails on hidden local state, not JSON syntax. A durable rollout commits the connection contract, keeps credentials personal, documents mutation policy, and includes a read-only acceptance test that every developer can repeat.

Commit the project configuration and repository instructions. Do not commit authentication artifacts. Then document a short onboarding contract:

1. Start Claude Code from the repository root.
2. Open /mcp and authenticate the linear server.
3. Run the read-only verification prompt with an accessible issue.
4. Confirm retrieved fields in Linear.
5. Do not permit issue mutations until repository verification passes.

Also decide what happens when Linear is unavailable. The correct fallback is not “let the agent reconstruct the ticket.” Either the prompt and repository contain enough authoritative detail to proceed, or the work pauses until the missing requirements are available.

For teams still defining basic agent boundaries, the free PairFoundry foundations track is the better starting point. Teams comparing more complete operating assets can use the PairFoundry packs overview.

The durable rule is simple: share configuration and policy, never shared identity; verify retrieved facts, never inferred ones; and keep code completion separate from external workflow mutation.

Related reading#

• Getting Jira MCP Claude Code right the first time
• Notion MCP Claude Code: what to check before you trust the connection

FAQ#

Should Linear issue text override repository documentation?#

No. Linear supplies task context, while the repository owns code-level invariants, tests, and implementation constraints. If they conflict, surface the conflict instead of silently choosing the newer-looking instruction.

How is this different from merely following the official Claude Code MCP setup?#

The official setup establishes connectivity. A production-ready team setup additionally defines project scope, per-developer authentication, mutation permissions, verification, and failure behavior. Those are repository operating decisions, so an external tool’s documentation cannot make them for you.

Should every developer use the same Linear credentials?#

No. Share the server declaration, not an account or authentication state. Each developer should authenticate separately so Linear permissions and auditability continue to reflect the human responsible for the session.

How do we roll back when Linear MCP starts failing?#

Stop external mutations first. Restart Claude Code from the repository root, inspect /mcp, reconnect the intended account, and repeat the read-only verification. If it still fails, work only from requirements already authoritative in the prompt or repository.

When should we avoid this Claude Code MCP integration?#

Do not use it when policy forbids exposing issue data to the agent, when developers cannot receive appropriate Linear access, or when the team expects MCP to replace missing acceptance criteria. The integration moves context across a defined boundary; it cannot repair an undefined workflow.