Guides

Linear for agents

Use Linear's own MCP server for the tools, and Linear webhooks so an issue assigned to an agent, an @mention, or a status change reaches it.

Agents use Linear in two halves:

Tools come from Linear's remote MCP server (https://mcp.linear.app/mcp), as an ordinary connection: sign in with OAuth, grant each agent the tools it needs, pin its team.
Events come from a Linear webhook to the office: an issue assigned to the agent's Linear user, an @mention of the agent, or a status change on an issue assigned to it.

1. Connect Linear#

Connections → Add connection → Linear, sign in, and grant agents tools (see Connections). Agents can act as the office's Linear account (one shared bot user) or each as its own Linear user (identity: agent).

2. Map agents to their Linear users#

Add an inbound block to connections/linear/connection.yaml (a policy PR):

title: Linear
url: https://mcp.linear.app/mcp
auth: oauth
identity: office
inbound:
  service: linear
  users:                                   # agent slug → its Linear user: ids, names or emails (any matches)
    ada: ["2f1c3a9e-0000-4000-8000-00000000a001", "ada"]
    sam: sam

Use the Linear user id so assignments match (Linear sends assigneeId), and the @name people type so mentions match (@ada, or the profile link /profiles/ada Linear puts in comments). An agent listed here that isn't in the policy is a policy error.

3. Add the webhook in Linear#

On the connection's Overview, the Inbound events card shows the URL. Choose Create webhook secret (shown once). In Linear: Settings → API → Webhooks → New webhook:

Field	Value
URL	`https://<office>/api/linear/webhook/linear`
Data change events	Issues, Comments
Signing secret	the webhook secret (or paste Linear's into the office with `officectl connections secret linear --key webhook_secret`)

Every delivery is checked against the Linear-Signature header (HMAC-SHA256 of the body), and its webhookTimestamp must be within a minute, so a replayed delivery is refused.

4. What reaches the agent#

In Linear	In the office
An issue is created with, or changed to, the agent as assignee	`linear.issue.assigned`
`@ada` in a comment, or in a new issue's description	`linear.mention`
An issue assigned to the agent changes status	Mail ("Dana set the status to Done on ENG-42")
Agent app notifications (`AppUserNotification`: assigned, mentioned, comment mention, status changed)	the same, matched on `appUserId`

With a matching rule the event starts an event run; without one it arrives as office mail. repos on a Linear rule lists team keys:

run:
  on:
    - event: linear.issue.assigned
      repos: [ENG]
      prompt: Triage it: reproduce, estimate, and comment your plan on the issue.
    - event: linear.mention

The agent answers with the Linear tools (linear__…). Changes the agent made itself are ignored. Each delivery is ledgered as linear.event.delivered and is delivered once: retries are dropped. If the Linear person's email belongs to someone in the office, the mail is from them; otherwise from the office.