Knowledge BaseKnowledge Base

Setting Up the Linear Connector

Connect Linear to Wazzi with one API key — let agents find, create and update issues, move them through your workflow, comment, and attach pull requests.

October 22, 2026
6 min read

Path: Connectors → Linear → Configuration

What this connector does

Linear is an issue tracker for software teams. The Linear connector exposes it to Wazzi as MCP tools, so agents and your team's AI assistants can read your issue queue, file new issues, move issues through your workflow states, comment, and attach links such as pull requests or preview deploys.

Wazzi authenticates with a personal API key. A Linear API key belongs to one Linear user, and everything the connector does shows in Linear as that user. That's why we recommend creating a dedicated user for your agents (for example Wazzi Agent) rather than using your own key. You enter the key here in Wazzi; there is no Linear sign-in screen.

The connector exposes 12 tools:

  • Workspace (5 tools) — get_viewer (who the connector acts as), list_teams, list_workflow_states, list_labels, list_users.
  • Issues (6 tools) — search_issues, get_issue, create_issue, update_issue, add_comment, attach_link.
  • Universal escape hatch (1 tool) — call_linear_graphql for anything not covered by a typed tool (projects, cycles, issue relations…).

Tools take names, not IDs: a team key (ENG), a state name (In Progress), label names (Bug) and an assignee email (or me / none). Wazzi looks up the IDs for you.

Before you start — getting your API key

  1. In Linear, invite a new member for your agents, e.g. Wazzi Agent, using an address you can receive email at. They need access to the teams the agents will work in. (A member takes a seat on your Linear plan.)
  2. Sign in to linear.app as that user.
  3. Open Settings → Account → Security & access and, under Personal API keys, click New API key.
  4. Give it a name (e.g. Wazzi). Where Linear offers it, limit the key to the teams and permissions the agents need — usually read, write, create issues and comments.
  5. Copy the key — it starts with lin_api_ and is only shown once. Treat it like a password.

[Screenshot placeholder: Linear → Settings → Security & access → Personal API keys, with New API key highlighted]

Using your own key while testing is fine — everything will just show as you, and Linear's suggested branch names will start with your username. Swap in the agent user's key before you rely on it.

Reference: Linear's API docs live at linear.app/developers.

What this connector unlocks for your team

Once configured, agents — and members with the right MCP permissions, from Claude or ChatGPT — can do things like:

  • "Find every Todo issue in the ENG team labelled agent and summarise them."
  • "File a bug in ENG: the owner statement page shows last month's totals. Priority high, label Bug."
  • "Move ENG-142 to In Review, comment with what changed, and attach the pull request link."
  • "What's assigned to me that hasn't moved in a week?"
  • "Give me the git branch name Linear suggests for ENG-142." (Use it for your branch and Linear links the PR to the issue automatically.)

Paired with the GitHub connector, an agent can pick up an issue, fix it in a checkout, open a pull request, and move the issue along — with a decision in Slack before anything ships.

Steps — configuring Linear in Wazzi

1. From the Connectors catalog, click Configure on the Linear tile.

You'll land on Linear's Configuration tab:

Linear connector Configuration tab

2. Fill in the fields.

  • Default Team (optional) — the team key used when a tool call names no team (the prefix of the team's issue IDs: ENG in ENG-123).
  • Personal API Key — the lin_api_… key from the agent user. Stored encrypted at rest in Wazzi.

3. Click Test Connection.

Wazzi asks Linear who the key belongs to. On success the green Connected banner appears at the top of the page, and the health check records the workspace and user — e.g. "Connected to Acme as Wazzi Agent".

4. Click Save Configuration.

Linear moves to the Active section of the catalog and the dot turns green. To let agents use it, make sure Agents is switched on for the connector, then add it to an AI step.

Troubleshooting

  • "You need to authenticate to access this operation." The key is wrong, revoked, or has trailing whitespace. Re-copy it (or create a new one) from the agent user's Security & access page.
  • "Name a team … this connector has no default team configured." The tool call didn't say which team and no Default Team is set. Either set one on the connector or pass team (use list_teams to see keys).
  • "No state "X" in this team. States: …" State names are per team. The error lists the valid ones; list_workflow_states shows them in board order.
  • "Unknown label(s): …" The label doesn't exist on that team or workspace-wide. Create it in Linear first, or check spelling with list_labels.
  • Search returns nothing you expected. search_issues uses the Default Team unless you pass team. Pass "*" to search every team.
  • Everything shows as you, not the agent. The key was created while signed in as you. Create one as the agent user and replace it.

Best practices

  • Use a dedicated agent user. It keeps a clean audit trail of what agents did, and you can remove its access without touching anyone's account.
  • Model your agent workflow as states. For example Todo → In Progress → In Review → In Staging → Ready for Production → Done. An agent only picks up issues in its starting state, so the state doubles as a lock and stops an issue being worked twice.
  • Use a label to opt issues in (e.g. agent), so agents never pick up work nobody meant for them.
  • Grant only the tools a group needs. Read-only groups don't need create_issue, update_issue or call_linear_graphql — see Managing Permissions.

Frequently asked questions

Does Wazzi store my API key in plaintext?
No. The key is encrypted at rest with per-org keys and only decrypted at the moment an outbound call is made.

Why doesn't it use Linear's own sign-in (OAuth)?
An agent runs on a schedule with nobody there to click "Allow". A key for a dedicated user works unattended, and you set it up once here.

Can I connect more than one Linear workspace?
Not yet — one workspace per Wazzi organization.

Can it archive or delete issues?
There's no typed tool for it on purpose. Archiving is possible through call_linear_graphql if a group is granted that tool.

What's next

Was this article helpful?