Linear MCP vs CLI vs API for AI Agents

For an AI agent working with a person in a conversation, use Linear’s MCP server: it signs in through the browser, can be held read-only, and needs no key on disk. For a job that runs the same steps every time, call Linear’s GraphQL API directly with a narrow personal API key, or a script built on it. A command-line tool sits between the two and suits coding agents that already live in a shell, but Linear does not publish one for everyday issue work, so any Linear CLI you install is a community project running on the same API and the same key. The choice is less about what each can reach, which overlaps heavily, and more about who holds the credential, how much of the model’s context each one uses, and what happens when something loops.

The same question for Jira, with Atlassian’s answers, is in Jira MCP vs the Jira API; the general case for any product is MCP vs REST API. This post is the Linear version, with the third option added.

The three routes at a glance

• MCP server: one hosted address, https://mcp.linear.app/mcp, run by Linear. The agent sees a list of tools and picks one mid-conversation. Sign-in is OAuth in the browser.
• CLI: a program on your machine that the agent runs as a shell command, such as linear issue list. It holds a Linear API key in an environment variable or a config file and calls the API for you.
• GraphQL API: https://api.linear.app/graphql, called by code someone wrote. It takes a personal API key or an OAuth app’s token and exposes everything Linear exposes to developers.

Route 1: the MCP server

According to Linear’s MCP documentation↗ (opens in a new tab), the server uses OAuth 2.1 with dynamic client registration, so a client such as Claude Code or Cursor registers itself, opens a browser, and you approve. You never see the token. The same page offers two ways to keep an agent read-only: a separate endpoint at https://mcp.linear.app/mcp/readonly, or the standard one with only the read scope granted, in which case the token cannot reach write APIs at all.

The server also accepts an API key or OAuth token in an Authorization: Bearer header, for machines with no browser. That is useful, but it turns the MCP route into a key-on-disk route, with the same care the API needs.

What you get in return for the sign-in is a curated set of tools that Linear maintains and widens over time. What the tools reach, object by object, is in what the Linear MCP server does, and setup is in Linear MCP with Claude Code and Linear MCP in Cursor.

Route 2: a command-line tool

Linear’s own command-line tool is its CLI importer↗ (opens in a new tab), an open-source tool for bringing issues in from services that have no dedicated import assistant. It is not a day-to-day interface for listing, creating and moving issues. Several community CLIs do that job, some of them written with agents in mind and printing JSON rather than tables. They are not Linear products, so check who maintains one, how recently it was updated and what it does with your key before you install it.

Structurally they all work the same way. The CLI stores a Linear API key, the agent runs a command through its shell tool, the CLI calls the GraphQL API and prints the answer, and the agent reads the output. Three consequences follow:

• The agent needs shell access. That suits Claude Code, Codex CLI or Cursor’s agent, which already run commands with your approval, and rules out chat apps with no terminal.
• The credential is a key on your machine, with whatever permissions you gave it. Nothing about the CLI narrows it further.
• Context is spent only on what the agent runs. It learns the commands from --help or from a note in your rules file, and each call costs the command plus its output. There is no list of tool definitions sitting in the conversation.

The last point is the usual argument for a CLI, and it is weaker than it was. Claude Code’s MCP documentation↗ (opens in a new tab) describes tool search, on by default, which loads only tool names at the start and fetches full definitions when Claude needs them. It also warns when one MCP result passes 10,000 tokens. Other clients differ, so check yours before you choose a route on context cost alone.

Route 3: the GraphQL API

Linear’s public API is GraphQL, the same API its own apps use. Linear’s GraphQL guide↗ (opens in a new tab) gives the endpoint and one detail that trips people up: a personal API key goes in the Authorization header on its own, while an OAuth access token is sent with Bearer in front.

curl -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  --data '{ "query": "{ issues(first: 10) { nodes { identifier title } } }" }'

The key is where you control what a script or CLI can do. Linear’s API and webhooks page↗ (opens in a new tab) says keys are created under Settings, Account, Security & Access, can have full access or be restricted to Read, Write, Admin, Create issues or Create comments, and can be limited to specific teams. Admins decide whether members may create keys at all, and existing keys can be revoked from the same menu. A key restricted to Read on one team is a much smaller thing to hand an agent than your whole account.

For anything other people install, the route is an OAuth application. Linear’s OAuth documentation lists scopes from read and write down to issues:create and comments:create, says access tokens last 24 hours and are refreshed, and offers actor=app, which makes the application, not the person who authorised it, the author of what it creates. Linear says that option is meant for agents and service accounts.

Rate limits

The API’s limits are published. Linear’s rate limiting page↗ (opens in a new tab) gives an API key 2,500 requests an hour per user and 3,000,000 complexity points an hour, an OAuth app 5,000 requests and 2,000,000 points, and caps any single query at 10,000 points. Going over returns HTTP 400 with a RATELIMITED error code, not a 429, so a retry loop written for other APIs may not notice. Headers such as X-RateLimit-Requests-Remaining say how close you are.

Because a CLI calls the same API with a key, it shares the key’s budget. Linear’s MCP documentation does not publish separate limits for the server. In practice the limit you meet first with an agent is rarely Linear’s: it is the conversation, which slows and summarises long before a script would run out of requests.

Which to use for which job

• Triage, summaries and drafting from a chat window: MCP, read-only first. The workflows that fit are in Linear MCP for product management.
• A coding agent filing and closing issues as it works in a repository: MCP if your client handles it well, or a CLI you trust with a key restricted to one team and to Create issues and Create comments.
• A nightly sync, a release job or a bulk edit of hundreds of issues: the API from a reviewed script, with a named key and a retry that understands RATELIMITED.
• An agent that should appear as itself in Linear rather than as you: an OAuth app with actor=app. Neither the MCP sign-in nor a personal key gives it its own name.
• A headless machine: the API, or the MCP server with a restricted key in the header. The browser sign-in needs a person.

Whichever you choose, start narrow. A read-only MCP connection or a Read-only key teaches you what the agent does with Linear before it can change anything. The wider habits are in MCP security best practices.

How fenbs answers the same question

fenbs has one door for agents, and it is MCP. There is no fenbs CLI, and the REST API page lists the endpoints but API keys are not available yet. A person connects an assistant with a browser sign-in, and a script or server that cannot open a browser uses a token issued by hand under Settings, with a name, the scopes you tick (read, write, comment) and an optional expiry. Both kinds of token act as the person, narrowed by their role on the board, and revoking one stops it at once. Every change is recorded in History under the assistant’s name, such as “Claude via Sam”, so the question “was that me or the agent?” has an answer.