MCP Spotlight: Linear MCP Server — The Official Engineering-Execution Bridge With Read-by-Default Tools, Project Status Updates, and the Issue-Tracking Default for Agents

Server: linear-mcp-server by Linear License: MIT (open source SDK) · Tools: ~25 (issues, projects, cycles, initiatives, teams, comments, customers) Coverage: The Linear project management platform — issues · projects · cycles · initiatives · milestones · roadmaps · teams · comments · customers · customer needs Transport: stdio (NPX) or HTTP · Auth: OAuth 2.0 (recommended) · Personal API Key (self-hosted) GitHub: github.com/linear/linear-mcp-server · linear.app/docs/mcp MCP Tracker: glama.ai/mcp/servers/linear

Every engineering-execution agent eventually needs Linear. The naive "give the agent a full personal API key" approach grants access to every workspace, every team, every project — and personal keys never expire. The "wrap Linear's GraphQL API as MCP" approach bloats the context window and gives the agent deep mutation power it doesn't need. The "give the agent nothing" approach blocks the entire engineering-execution automation category.

The official Linear MCP Server by Linear is the bridge that resolves this. ~25 tools covering the Linear collaboration surface — issues, projects, cycles, initiatives, teams, comments, customers — built around read-by-default semantics (Linear's read tools are the most-used, write tools are gated). MIT-licensed, official Linear-maintained.

This is the engineering-execution default for AI agents in 2026. Project-tracking native, OAuth-scoped, ubiquitous use in modern software teams.

The Architecture: Linear-Native Tool Surface

The Linear MCP Server's tool surface is organized around how Linear work actually flows:

Category	Tools	Purpose
Issues	~6 tools: list, get, create, update, archive, comment	Issue lifecycle
Projects	~4 tools: list, get, create, update	Project management
Project Updates	~2 tools: create, list	Status reporting (new in 2026)
Cycles	~2 tools: list, get	Sprint/cycle management
Initiatives	~2 tools: list, get	Strategic grouping
Teams	~2 tools: list, get	Workspace navigation
Comments	~2 tools: add, list	Collaboration
Customers / Needs	~3 tools: list, get, attach	Customer-feedback linkage
Users	~2 tools: list, get	Workspace navigation

The tools are focused on what agents actually do in Linear: query state, update issues, manage projects, post status updates, attach customer feedback.

The Read-by-Default Pattern

Linear's most-used operations are reads: "what's in this cycle?", "what's the project status?", "show me issues assigned to me." The Linear MCP server's tool descriptions reflect this — read tools have rich descriptions that guide the agent toward efficient patterns:

list_issues(
  query: "is:open assignee:me priority:high",
  limit: 20
)
  → Returns issues matching the filter

The agent learns Linear's GraphQL-style filter syntax from the tool descriptions. Filters like is:open, assignee:me, priority:high are first-class in the read tools.

For write operations, the description explicitly indicates the destructive surface:

create_issue(
  title: "Add rate limiting to /api/auth",
  description: "...",
  teamId: "...",
  priority: 2,
  labelIds: ["..."]
)
  → Returns the created issue

The agent gets clear feedback on what each operation does. No surprise mutations.

The Killer Combination: Issue + Project + Cycle

The three highest-leverage primitives:

Issue lifecycle

list_issues(
  filter={
    "state": {"type": {"eq": "started"}},
    "assignee": {"id": {"eq": "user_kevin"}},
    "priority": {"gte": 2}
  },
  sort="-priority",
  limit=20
)
  → Returns prioritized issues assigned to Kevin

create_issue(
  title="Fix auth validation for empty emails",
  description="## Problem\n...",
  teamId="team_engineering",
  priority=2,
  labelIds=["label_bug", "label_security"],
  projectId="project_auth_migration",
  cycleId="cycle_q3_sprint_3"
)
  → Returns the issue

update_issue(
  id="issue_abc123",
  stateId="state_in_progress"
)
  → Updates the issue state

The agent navigates the issue queue, creates new issues, transitions states, all within Linear's structured workflow.

Project management

list_projects(
  filter={"state": {"eq": "started"}},
  limit=10
)
  → Returns active projects

get_project(id="project_xyz")
  → Returns full project details (description, lead, members, milestones)

create_project_update(
  projectId="project_xyz",
  body="## Status\n- Auth Migration: 60% complete\n- Rate Limiting: Not started\n- Blockers: None",
  health="onTrack"
)
  → Posts the status update (visible to stakeholders)

The agent manages projects, posts status updates — the work that engineering leads do every week.

Cycle management

list_cycles(
  filter={"isActive": {"eq": true}},
  teamId="team_engineering"
)
  → Returns active cycles

get_cycle(id="cycle_q3_sprint_3")
  → Returns cycle details (start, end, progress, issues)

move_issue_to_cycle(
  issueId="issue_abc",
  cycleId="cycle_q3_sprint_4"
)
  → Reschedules the issue

The agent manages sprint/cycle assignments, reschedules, tracks progress.

The Issue Workflow

The canonical agent-driven Linear workflow:

User: "Triage this week's new issues in the Engineering team."

Agent:
  1. list_teams()
     → Returns teams, finds "Engineering"
  2. list_issues(
       filter={
         "team": {"id": {"eq": "team_engineering"}},
         "createdAt": {"gte": "2026-07-23"}
       },
       sort="-createdAt",
       limit=50
     )
     → Returns this week's new issues
  3. For each issue:
     a. get_issue(id)
     b. Categorize by content (bug, feature, task)
     c. Suggest priority, assignee, project
  4. update_issue(id, priority, assigneeId, projectId)
     → Updates the issue
  5. Returns the triage report

The agent iterates the new-issue queue, suggests triage decisions, applies updates.

The Project Status Update Pattern

For agents that participate in project management:

User: "Generate this week's status update for the Auth Migration project."

Agent:
  1. get_project(id="project_auth_migration")
     → Returns project details
  2. list_issues(
       filter={"project": {"id": {"eq": "project_auth_migration"}}}
     )
     → Returns all project issues
  3. Group by state (todo, in progress, done)
  4. Calculate progress (% complete, blockers, timeline)
  5. create_project_update(
       projectId="project_auth_migration",
       body="## Status\n- 60% complete\n- 12 issues done, 8 in progress, 4 todo\n- Blockers: None\n- ETA: Sept 30",
       health="onTrack"
     )
     → Posts the status update

The agent does the synthesis that engineering leads do every week.

The Customer Feedback Linkage

For agents that participate in customer-feedback workflows:

list_customers()
  → Returns customers

list_customer_needs(
  customerId="customer_acme",
  filter={"status": {"eq": "open"}}
)
  → Returns Acme's open needs

create_issue(
  title="Add SAML SSO for Acme (per their request)",
  description="## Customer Need\n...",
  teamId="team_engineering",
  customerNeedId="need_xyz"
)
  → Returns the issue linked to the customer need

The agent converts customer feedback into engineering work, with the linkage preserved.

The OAuth 2.0 Flow

For SaaS-embedded agents (or any multi-user setup), OAuth 2.0 is the right primitive:

1. User initiates — "Connect Linear" button
2. OAuth redirect — user authorizes on linear.app, sees the requested scopes
3. Token storage — the SaaS receives an access + refresh token, stores per-user
4. Agent acts — every Linear MCP call uses the user's access token
5. Refresh flow — the SaaS refreshes the token automatically

The scopes are principle-of-least-privilege:

Scope	Allows
read	View issues, projects, cycles, etc.
write	Create + update issues, projects
issues:create	Create new issues only
comments:create	Add comments only

For an agent that just reads + posts status updates, the scopes are read + minimal write for the specific operations needed. The user sees the scopes on the OAuth screen and approves.

Facio Integration

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "${credentials.LINEAR_OAUTH_TOKEN}"
      }
    }
  }
}

Or use the official Personal API Key (for self-hosted):

# Generate at https://linear.app/settings/api
LINEAR_PERSONAL_KEY=lin_api_...

Critical: For production SaaS deployments, OAuth 2.0 is the right primitive — each user authorizes their own Linear workspace, the agent acts on their behalf. Personal API keys are for self-hosted, single-user scenarios.

Facio's audit trail captures every Linear MCP call with the tool, the issue/project ID, the operation, the parameters, and the result. For a regulated team (SOC2, ISO 27001), this is the complete engineering-execution record: "Agent at 14:32 UTC created issue ENG-1234 'Fix auth validation', assigned to Alice, priority High, project Auth Migration."

For HITL workflows, the Linear MCP server's destructive surface is significant — agents can create issues, transition states, post updates:

Tool	Severity	Suggested Gate
list_*, get_*, search_*	Read	None — autonomous
add_comment	Write, contextual	Soft confirm
create_issue	Write, contextual	Soft confirm
update_issue (state, priority, assignee)	Write, contextual	Soft confirm
archive_issue	Write, contextual	Soft confirm
create_project	Write, contextual	Soft confirm
update_project	Write, contextual	Soft confirm
create_project_update	Write, contextual (visible to stakeholders)	Hard confirm (status report)
delete_* (when available)	Write, destructive	Hard confirm + reason

The create_project_update tool deserves special attention — project updates are visible to all stakeholders (engineering leads, executives, customers in some configs). Facio should require hard confirmation with the operator reviewing:

• The project the update is for
• The body content
• The health status (onTrack, atRisk, offTrack)
• The visibility (who can see it)

For multi-team setups (one Linear workspace per org, per product), the pattern is one OAuth integration per workspace. The agent switches context per workspace, the audit trail is per-workspace.

For multi-tenant SaaS setups, per-user OAuth tokens are essential. Each user authorizes their own Linear workspace, the agent acts on their behalf, the audit trail records which user authorized which action.

Quickstart

# 1. Create a Linear OAuth application
#    https://linear.app/settings/api/applications
#    Scopes: read, write (as needed)
#    Redirect URI: <your-app>/oauth/linear/callback

# 2. Install the MCP server
npm install -g @linear/mcp-server

# 3. Configure your MCP client
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "lin_api_..."  // or OAuth token
      }
    }
  }
}

# 4. First prompts
# "Show me my open issues, prioritized"
# "Create a new issue for the auth bug fix"
# "Generate this week's status update for the Auth Migration project"
# "Move issue ENG-1234 to the Q3 Sprint 4 cycle"
# "Find customer needs from Acme that aren't addressed yet"

Use Cases

Issue triage: "Triage this week's new issues. Categorize by area, assign priority, suggest assignees based on team." Multi-issue batch processing.

Sprint planning: "Plan the next cycle. Find issues from the backlog that fit the cycle capacity." Backlog grooming + capacity planning.

Status reporting: "Generate this week's status update for the Auth Migration project." Cross-issue aggregation → stakeholder update.

Customer feedback integration: "Find every customer need from Acme that isn't addressed yet. Create issues for the top priorities." Cross-customer analysis.

Standup aggregation: "Generate the daily standup report. Show what each teammate did yesterday and plans for today." Cross-user issue activity.

Blocker detection: "Find every issue marked as blocked. Identify the top 3 by age and flag for resolution." Blocker triage.

Capacity planning: "For each active cycle, show progress vs. time elapsed. Flag cycles that are behind." Cycle progress analysis.

Roadmap tracking: "Show me the Q3 roadmap. For each initiative, what's the current status?" Initiative aggregation.

Release coordination: "Find every issue tagged with the v2.3.4 release. Show progress and blockers." Release-bucket aggregation.

Workload balancing: "Show me the issue count per team member. Flag anyone significantly above or below average." Load distribution analysis.

Dependency tracking: "Find issues with 'blocked by' relations. Identify the critical path." Dependency graph analysis.

Label cleanup: "Find issues with no labels. Suggest labels based on the issue content." Auto-labeling.

Team velocity: "For each team, calculate the average issues completed per cycle. Show trends." Velocity metrics.

Burndown analysis: "For the active cycle, generate the burndown chart. Show actual vs. planned." Cycle burndown.

Customer request tracking: "Find every issue linked to customer needs. Show the customer → request → status chain." Customer traceability.

Cross-project migration: "Find issues that should move from project X to project Y. Propose the migration plan." Project reorganization.

Stale issue detection: "Find issues with no activity in 30+ days. Suggest closing or escalating." Stale-issue triage.

Priority review: "Find every P0 issue. Show current state and assignee. Flag any unassigned." Priority queue audit.

Cycle retrospective: "Generate the retrospective for the just-closed cycle. What went well, what didn't, what to change." Cycle retrospective.

Resource allocation: "For each team, show the breakdown of issues by project. Identify over- and under-allocation." Resource analysis.

The Read-by-Default Tool Design Pattern

The Linear MCP server's defining design choice — read tools are the most-used, write tools are gated, descriptions guide efficient patterns — is the design lesson every "collaboration-as-MCP" server should copy.

Why read-by-default wins:

• Most agent operations are reads — "show me", "find", "what's the status"
• Read tools are zero-blast-radius — no destructive surface
• Write tools are explicit — the operator knows what the agent can mutate
• Filter syntax is first-class — the agent learns the structured query language
• Description discipline guides efficient use — the tool descriptions are the prompt

For any collaboration platform (Linear, Jira, Notion, Asana, GitHub), read-by-default is the right design. The agent's primary need is context; write operations are explicit and gated.

The Filter-as-API Pattern

The Linear MCP server's second defining design choice — expose the filter syntax as a structured input — is the design lesson every "query-heavy-as-MCP" server should copy.

Linear's filter syntax is structured, not stringly-typed:

filter={
  "state": {"type": {"eq": "started"}},
  "assignee": {"id": {"eq": "user_kevin"}},
  "priority": {"gte": 2},
  "createdAt": {"gte": "2026-07-23"}
}

The agent constructs filters using typed objects, not raw strings. No SQL injection equivalent, no parse errors, no ambiguous semantics.

The pattern applies to:

• Jira MCP — JQL as structured filter
• GitHub MCP — search query as structured filter
• Stripe MCP — list filters as structured filter
• HubSpot MCP — search filters as structured filter

For any "query-heavy" service, structured filters are the right primitive. String queries are fragile; structured filters are composable.

The Project Update Primitive

The Linear MCP server's third defining innovation — create_project_update as a first-class tool for stakeholder communication — is the design lesson every "project-management-as-MCP" server should copy.

Why project updates win:

• Stakeholder visibility — executives, customers, and team members see the status
• Health tracking — onTrack, atRisk, offTrack flags aggregate state
• Historical record — every project's status over time is preserved
• Agent-friendly — the agent can synthesize updates from issue data
• Auditable — the update is attributed to the agent, not the operator

For any project-management MCP server, the status update primitive is the right complement to issue/project CRUD. The agent doesn't just mutate issues; it communicates the state to stakeholders.

Bottom Line

The Linear MCP Server is the engineering-execution default for AI agents in 2026. ~25 focused tools covering issues, projects, cycles, initiatives, customers, with read-by-default semantics and structured filters. MIT-licensed, official Linear-maintained.

For any agent that participates in engineering execution — issue triage, sprint planning, status reporting, customer feedback integration, standup aggregation, capacity planning — this is the bridge. The agent reads Linear state, updates issues, posts project updates, links customer needs. All with structured filters, all with OAuth-scoped access.

For the broader MCP ecosystem, the Linear pattern is the design lesson every "collaboration-as-MCP" server should copy. Read-by-default tools + structured filters + project update primitive. When the project-management primitive is right, the agent's engineering execution is right.

npx -y @linear/mcp-server with LINEAR_API_KEY=lin_api_... (or OAuth token) and your agent has Linear.

---

MCP Spotlight is a series covering servers that give AI agents real capabilities. Every server is evaluated for design clarity, ecosystem impact, and integration fit with Facio's HITL-first agent runtime.