Skip to main content
Table of Contents

Connect to LinearB MCP Server

Connect AI tools and IDE assistants to LinearB using MCP. Supports Claude, Cursor, VS Code, Codex, and more with step-by-step setup.

Steven Silverstone
Updated by Steven Silverstone
Table of Contents

Connect your AI tools and IDE assistants to LinearB to query engineering data, generate insights, and build custom workflows using MCP.

For an overview of how MCP works, see: LinearB MCP Server Overview & Use Cases .

Estimated setup time: 2–5 minutes

Quick Start

If you are unsure where to begin:

  • Use any MCP-compatible client (such as Claude Desktop or Cursor)
  • Use OAuth (or API key)
  • Use this MCP endpoint: https://mcp.linearb.io/mcp

Then open your tool, follow its setup steps, and approve access when prompted.

Connection Methods

  • Secure, user-based authentication
  • No API keys required
  • Supported by most modern MCP clients

API Key (Alternative)

  • Used for clients that do not support OAuth
  • Requires generating a LinearB API key
  • Recommended only when OAuth is not available

Choose Your Client

How Authentication Works

Authentication behavior depends on your client:

  • Some tools show a Connect prompt when MCP is first used
  • Some tools open the browser automatically
  • CLI tools require running an authentication command

All OAuth flows redirect to LinearB for secure approval.

How to Verify It’s Working

  • Your client shows the MCP server as Connected
  • You can query LinearB data, such as pull requests or metrics
  • You are not repeatedly prompted to authenticate

Example Queries

After connecting, try asking your AI tool:

  • Show me PRs merged this week
  • Which teams have the highest cycle time?

Claude Desktop

Connect using OAuth (UI)

Use Claude Desktop to connect via the Connectors UI.

  1. Open Claude Desktop
  2. Go to Settings → Connectors
  3. Click Manage Connectors
  4. Click Add custom connector
  5. Enter: https://mcp.linearb.io/mcp
  6. Save the connector

What happens next:

  • When you first use LinearB, Claude will prompt you to Connect
  • Click Connect
  • Your browser opens automatically
  • Sign in to LinearB and approve access
  • Return to Claude and confirm the connection is active
Custom connectors may require a paid Claude plan, such as Pro, Max, Team, or Enterprise.

Official documentation: Anthropic Docs

Claude Code

Connect using CLI

Add the MCP server:

claude mcp add --transport http linearb https://mcp.linearb.io/mcp

Optional scope:

User-level

claude mcp add --transport http linearb https://mcp.linearb.io/mcp --scope user

Project-level

claude mcp add --transport http linearb https://mcp.linearb.io/mcp --scope project

Authenticate:

  1. Run /mcp
  2. Select linearb
  3. Choose Authenticate
  4. Approve access in your browser

Official documentation: Anthropic Docs

Cline

Configure Cline

Cline requires mcp-remote. 

{
            "mcpServers": {
              "linearb": {
                "command": "npx",
                "args": [
                  "@modelcontextprotocol/mcp-remote",
                  "https://mcp.linearb.io/mcp"
                ]
              }
            }
          }

Codex

Connect LinearB to Codex

Add the LinearB MCP server, then sign in with OAuth: 

codex mcp add linearb --url https://mcp.linearb.io/mcp
codex mcp login linearb

Complete the authorization flow in your browser. After authorization, return to Codex and confirm that the LinearB MCP server is connected.

Attribute Codex-assisted Git commits

You can add a persistent instruction that asks Codex to identify commits it materially contributes to. Your configured Git identity remains the primary author, while Codex is recorded as a co-author.

Codex Desktop

  1. Open a task in Codex Desktop.
  2. Ask Codex to add the rule below to your global ~/.codex/AGENTS.md file.
  3. Review and approve the proposed file change.
  4. Start a new task so Codex loads the updated global instructions.

Codex CLI

  1. Open or create ~/.codex/AGENTS.md.
  2. Add the rule below.
  3. Start a new Codex session so the updated instructions are loaded.
# Git commits
          
          - Whenever you create a Git commit for changes you materially contributed to, keep my configured Git identity as the primary author.
          - Append exactly one Git trailer after a blank line: `Co-authored-by: Codex <codex@openai.com>`
          - Do not duplicate the trailer. Verify the complete message before finishing.

To verify the author and complete commit message, run: 

git show -s --format=fuller HEAD
This rule applies to future Codex tasks and sessions. It does not change existing commits or add a trailer when Codex did not materially contribute to the changes.

Official documentation: Custom instructions with AGENTS.md

Cursor

Configure Cursor

OAuth (recommended):

Example configuration for Cursor: 

{
            "mcpServers": {
              "linearb": {
                "url": "https://mcp.linearb.io/mcp"
              }
            }
          }

API key (alternative):

Example configuration for Cursor using an API key: 

// MCP server using HTTP or SSE - runs on a server
          {
            "mcpServers": {
              "linearb": {
                "url": "https://mcp.linearb.io/mcp",
                "headers": {
                  "API_KEY": "LINEARB_ADMIN_API_KEY"
                }
              }
            }
          }

What happens next:

  • Restart Cursor
  • Your browser opens automatically
  • Sign in to LinearB and approve access

Official documentation: Cursor Docs

VS Code

Configure VS Code 
{
            "servers": {
              "linearb": {
                "type": "http",
                "url": "https://mcp.linearb.io/mcp"
              }
            }
          }

Official documentation: VS Code Docs

Windsurf

Configure Windsurf

Windsurf supports OAuth natively. 

{
            "mcpServers": {
              "linearb": {
                "serverUrl": "https://mcp.linearb.io/mcp"
              }
            }
          }

Official documentation: Windsurf / Codeium

Zed

Configure Zed

Zed requires mcp-remote.

Example configuration for Zed: 

{
            "context_servers": {
              "linearb": {
                "command": "npx",
                "args": [
                  "-y",
                  "@modelcontextprotocol/mcp-remote",
                  "https://mcp.linearb.io/mcp"
                ]
              }
            }
          }

Official documentation: Zed Docs

API key example for Zed: 

{
            "context_servers": {
              "linearb": {
                "settings": {},
                "url": "https://mcp.linearb.io/mcp",
                "headers": {
                  "x-api-key": "LINEARB_ADMIN_API_KEY"
                }
              }
            }
          }

Using API Key (Alternative)

  1. Go to Settings → API Tokens in LinearB
  2. Generate a new API key
  3. Use the key in your MCP client configuration

Example configuration using an API key: 

{
            "context_servers": {
              "linearb": {
                "settings": {},
                "url": "https://mcp.linearb.io/mcp",
                "headers": {
                  "x-api-key": "LINEARB_ADMIN_API_KEY"
                }
              }
            }
          }
Use API key authentication only if your MCP client does not support OAuth or requires static credentials.
Note:
MCP Remote (advanced / optional)

Most modern MCP clients do not require mcp-remote. Only use it if explicitly required by your client configuration.

Install globally: 
npm install -g @modelcontextprotocol/mcp-remote

Troubleshooting

  • Restart your client after configuration
  • Ensure you are a Company Admin
  • Confirm you are in the correct LinearB workspace
  • If the browser does not open, your client may not support OAuth

This guide reflects current MCP client behavior and may evolve as tools update their integrations.

How did we do?

LinearB MCP Server Connectivity Architecture

Contact