Connect your AI Agents to Linear in minutes
Available tools
create_comment
Creates a new comment
resolve_comment
Resolves a comment
unresolve_comment
Unresolves a comment
update_comment
Updates a comment
get_comment
Get a single comment by ID
get_comments
Get comments with filtering and pagination. Filter by issue (supports 'TEAM-123' identifiers), body text, dates. Returns comment details with user and issue info.
list_cycles
Get a list of cycles from Linear. Supports filtering, pagination (first, last, before, after), and returns all fields as per the Linear Cycle schema. Returns nodes and pageInfo
get_issue_labels
Get a list of IssueLabel objects from Linear
create_issue_label
Creates a new issue label
list_issue_statuses
Get a list of issue statuses from Linear (workflow states). Supports filtering and pagination
get_issues
Get a list of issues from Linear with filtering and pagination support. IMPORTANT: For pagination, use EITHER forward_pagination OR backward_pagination, never both simultaneously. If using forward_pagination, set backward_pagination to null. If using backward_pagination, set forward_pagination to null. Returns nodes and pageInfo following Linear Issue schema. For specific issues by ID/identifier, use the ID field in filter.
get_issue
Get a single issue by ID from Linear. Returns all fields as per the Linear Issue schema
create_issue
Create Linear issue with title, description, priority, assignee, labels, estimates, dates, icon, sub-issue order. Supports team, project, cycle, parent, subscribers. Use child labels only.
update_issue
Update Linear issue fields (title, description, priority, assignee, state, labels, dates, project, cycle, subscribers, icon, sub-issue order). To CLEAR a nullable field, use its boolean flag: unset_parent, unset_assignee, unset_project, unset_cycle, unset_due_date — passing null for these is ignored. Use child labels only.
archive_issue
Archive (delete) an issue in Linear by ID
get_projects
Get a list of projects from Linear. Supports pagination and returns all fields as per the Linear Project schema. Returns nodes and pageInfo. It is recommended to pull in no more than 20 items at a time. If you need more, use pagination. Requesting too much data can result in a query complexity error from Linear
get_project
Get a single project by ID from Linear. Returns all fields as per the Linear Project schema
create_project
Create a new project in Linear with comprehensive field validation. Supports all major project properties including statusId, description, team assignments, dates, labels, and member management. Automatically validates field types and constraints per Linear API requirements.
update_project
Update an existing project in Linear. Use statusId (not state) to change project status.
archive_project
Archive a project in Linear by ID
get_project_updates
Get project updates from Linear. Supports optional project_id targeting, advanced filter usage, pagination, and includeArchived.
get_project_update
Get a single project update by ID from Linear.
create_project_update
Create a project update in Linear using body text and optional health/diff visibility.
update_project_update
Update an existing project update in Linear.
archive_project_update
Archive a project update in Linear by ID.
unarchive_project_update
Unarchive a project update in Linear by ID.
get_teams
Get a list of teams from Linear. Supports filtering by name/key and pagination
get_team
Get a team by id from Linear
create_team
Create a team in Linear
update_team
Update a team in Linear
get_users
Get a list of users from Linear. Supports pagination. Linear's API does not support CRUD operations on Users
get_user
Get a single user from Linear by ID
validate_credential
Validate Linear credentials. Verifies credentials during setup.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's Linear MCP server
FAQs on using Merge's Linear MCP server
What makes Merge Agent Handler’s Linear MCP server better than alternative options?
- Managed authentication and credential lifecycle: Merge handles connector onboarding, dynamic auth flows, token management, and credential validation so agents can call Linear tools securely without handling OAuth flows directly
- Security gateway with DLP: Tool inputs and outputs are scanned for sensitive data. You can also set rules to block, redact, or log certain agent behaviors. This capability isn't provided by standalone MCP servers
- Real-time observability and complete audit logs: Merge provides full tool-call logging, searchable activity history, and visibility into every API request made by an agent. This creates a comprehensive audit trail
- Connector Studio for customization: Teams can modify Linear’s connector, add new tools, or customize existing ones
What are popular tools for Linear’s MCP server?
- Issue Tools: Find, create, update, or retrieve issues by using tools like get_issue, create_issue, and update_issue
- Project Tools: Query or update project data via tools like archive_project, create_project, and get_projects
- Comment Tools: Add, update, or retrieve comments on issues with tools like resolve_comment, create_comment, and get_comment
What are some common use cases for the Linear MCP server?
- Combine data sources for broader insights: Your analysts can combine information from Linear with other data sources (e.g., your data warehouse) to uncover broader insights, such as the impact product bugs have on feature adoption
- Get context on issues or projects: Your support team can retrieve information on specific issues from an app like Slack to understand their status, details, and history
- Receive consistent updates: Your product leadership team can receive weekly summaries of the product-specific tickets created in Linear over the past week within Slack
How does Merge Agent Handler manage authentication?
Merge automates the full authentication lifecycle. This includes:
- Dynamic authorization flows
- Built-in credential management
- Shared or individual auth per connector
For Linear specifically, users authenticate through Merge’s Link flow, and Merge manages OAuth tokens before executing any MCP tool calls.
Can I set custom security rules for Linear tool calls?
Yes. Merge’s Security Gateway supports both default and fully custom DLP rules. You can configure rules to:
- Block Linear tool calls containing sensitive data
- Redact response fields
- Mask specific patterns
- Enforce organization-level data governance
These rules apply to both tool inputs and outputs.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
