Linear Subagent Guide

⛔ EXACT LINEAR MCP PARAMETERS (VERIFIED)

These are the EXACT parameter names from get_server_tools. Copy exactly.

Most Common Operations

// GET ISSUE - uses "id"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "get_issue",
  args: { id: "WORK-26" }  // ✅ CORRECT - "id" not "issueId"
})

// UPDATE ISSUE - uses "id"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "update_issue",
  args: {
    id: "WORK-26",        // ✅ CORRECT - "id" not "issueId"
    description: "...",
    state: "In Progress"
  }
})

// CREATE COMMENT - uses "issueId"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "create_comment",
  args: {
    issueId: "WORK-26",   // ✅ CORRECT - "issueId" for comments
    body: "Comment text"
  }
})

// LIST COMMENTS - uses "issueId"
mcp__agent-mcp-gateway__execute_tool({
  server: "linear",
  tool: "list_comments",
  args: { issueId: "WORK-26" }  // ✅ CORRECT
})

Parameter Reference Table

---

Overview

The Linear subagent (ccpm:linear-operations) is a dedicated MCP handler that optimizes all Linear API operations in CCPM. Rather than making direct Linear MCP calls, commands should delegate to this subagent, which provides:

• 50-60% token reduction (15k-25k → 8k-12k per workflow)
• Session-level caching with 85-95% hit rates
• Performance: <50ms for cached operations (vs 400-600ms direct)
• Structured error handling with actionable suggestions
• Centralized logic for Linear operations consistency

When to Use the Linear Subagent

Use the subagent for:

• Reading issues, projects, teams, statuses
• Creating or updating issues, projects
• Managing labels and comments
• Fetching documents and cycles
• Searching Linear documentation

Never use the subagent for:

• Local file operations
• Git commands
• External API calls (except Linear)

---

⚠️ CRITICAL: Parameter Name Gotcha

Different Linear MCP tools use different parameter names for issue IDs:

First-call failures are often caused by using issueId instead of id for get_issue/update_issue.

---

Available Linear MCP Tools (Complete Reference)

Linear MCP provides 23 tools for interacting with Linear. This is the complete, validated list.

---

1. Comments (2 tools)

list_comments

List comments for a specific Linear issue.

Parameters:

• issueId (string, required) - The issue ID

Example:

mcp__linear__list_comments({ issueId: "PSN-41" })

create_comment

Create a comment on a specific Linear issue.

Parameters:

• issueId (string, required) - The issue ID
• body (string, required) - The content of the comment as Markdown
• parentId (string, optional) - A parent comment ID to reply to

Linear's Native Collapsible Syntax: Use +++ to create collapsible sections (starts collapsed, native Linear feature):

+++ Section Title
Content here (multi-line markdown supported)
+++

Example (simple):

mcp__linear__create_comment({
  issueId: "PSN-41",
  body: "## Progress Update\n\nCompleted first phase."
})

Example (with collapsible section):

mcp__linear__create_comment({
  issueId: "PSN-41",
  body: `🔄 **Progress Update**

Completed first phase, all tests passing

+++ 📋 Detailed Context
**Changed Files:**
- src/auth.ts
- src/tests/auth.test.ts

**Next Steps:**
- Implement phase 2
- Update documentation
+++`
})

---

2. Cycles (1 tool)

list_cycles

Retrieve cycles for a specific Linear team.

Parameters:

• teamId (string, required) - The team ID
• type (string, optional) - "current", "previous", or "next"

Example:

mcp__linear__list_cycles({ teamId: "team-123", type: "current" })

---

3. Documents (2 tools)

get_document

Retrieve a Linear document by ID or slug.

Parameters:

• id (string, required) - The document ID or slug

Example:

mcp__linear__get_document({ id: "doc-abc-123" })

`list_document

...