> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Linear integration Connect Linear so that an Agent can create, update, and find issues, list teams and projects, and add comments. You can add Linear tools to an Agent or to a prompt step in a Flow. Linear does not have a dedicated Flow step. ## Before you begin Create a personal API key in [Linear Settings > API](https://linear.app/settings/api). Linear API keys start with `lin_api_`. Treat the key as a password. ## Connect Linear To connect Linear and add its tools to an Agent, follow these steps: 1. Open the Agent, and click **Add tool**. 2. Find **Linear**, and click **Set up**. 3. Paste your key in the **API key** field. 4. Click **Connect Linear**. Runtype adds all Linear tools to the Agent. 5. Optional: In the **Linear** row, clear the tools that the Agent does not need. 6. Click **Save version**. Runtype saves the key to your account in the current organization. Your Agents and prompt steps with Linear tools use it. Runtype doesn't check the key when you save it, so verify the connection. ## Verify the connection Run the Agent and ask it to list your Linear teams. If the Agent returns your teams, the key works. The result also gives you the team IDs that `create_issue` needs. ## Available tools The following table lists the Linear tools. In Agent instructions, refer to a tool by the name that the model sees, such as `linear_create_issue`. | Tool | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `create_issue` | Creates an issue. Requires a title and a team ID. Optionally sets a description, assignee, priority, state, labels, project, and estimate. | | `update_issue` | Changes an issue's title, description, assignee, priority, or state. It cannot change labels, project, or estimate. | | `search_issues` | Lists issues, filtered by team ID or assignee ID. Returns 25 issues by default. Set `limit` to return up to 100. | | `get_issue` | Gets one issue by ID or by identifier, such as `ENG-123`. | | `list_teams` | Lists the teams in the workspace, with their IDs. | | `list_projects` | Lists projects, optionally filtered by team ID. | | `add_comment` | Adds a comment to an issue. | ### Work with Linear IDs Linear tools take IDs, not names, for teams, users, workflow states, labels, and projects. Add `list_teams` with `create_issue` so that the Agent can find the team ID. Add `list_projects` if the Agent sets projects. No Linear tool lists users, workflow states, or labels. To assign issues, change their state, or add labels, copy the IDs from Linear and put them in the Agent's instructions. Priority is a number: `0` None, `1` Urgent, `2` High, `3` Medium, `4` Low. > **Note** > > `search_issues` doesn't filter by search text or state name. It accepts a `query` and a > `state` value but ignores them, and returns unfiltered issues for the team or assignee. To > find a specific issue, use `get_issue` with its identifier, or tell the Agent to check > the titles in the results. ## Connect with the API To save the key with the API, send it to the Linear credentials endpoint. The API key that you use needs the `INTEGRATIONS:WRITE` scope. **`Save a Linear key`** ```bash title="Save a Linear key" curl -X POST https://api.runtype.com/v1/integrations/linear/credentials \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"apiKey": "lin_api_YOUR_LINEAR_KEY"}' ``` Replace the following: * `YOUR_API_KEY`: your Runtype API key. * `lin_api_YOUR_LINEAR_KEY`: your Linear API key. A request without `apiKey` fails with `apiKey is required for Linear`. To replace the key, send the request again with the new key. By default, the key applies to all environments. To save a key for one environment, add `"environment": "development"` or `"environment": "production"` to the body. A run uses the key for its environment. If that environment has no key, the run uses the all-environments key. To attach Linear tools to an Agent, add their IDs to the Agent's `tools.toolIds`. Linear tool IDs use the form `builtin:linear:`: **`Agent tools`** ```json title="Agent tools" { "tools": { "toolIds": ["builtin:linear:list_teams", "builtin:linear:create_issue"] } } ``` ## Use cases Use Linear tools for the following tasks: * **Bug reporting**: Create issues from customer feedback. * **Feature requests**: Track requests from chat conversations. * **Escalations**: Create urgent issues when a run finds a problem. * **Monitoring**: Log anomalies from scheduled runs. ## Troubleshooting * **`Linear API error: ...`**: Linear rejected the request. If the message is about authentication, the key is wrong or revoked. Create a new key in Linear, and save it again. Otherwise, check the IDs that the Agent sent. * **`MCP server "linear" not configured`**: No key exists for the run's environment. The message points to **Settings > Integrations**, but Linear is not listed there. Connect Linear from the Agent's **Add tool** list, or save a key with the API for all environments or for the environment that the run uses. * **The Agent can't create an issue**: `create_issue` requires a team ID. Add `list_teams` to the Agent, or put the team ID in its instructions. ## Remove Linear access To stop an Agent from using Linear, remove its Linear tools in the Agent editor, and click **Save version**. To stop all Linear access, revoke the API key in Linear. After that, Linear tools return a Linear API error. To delete the stored key from Runtype, send a `DELETE` request to `/v1/integrations/linear/credentials`. Without a query parameter, the request deletes the all-environments key. To delete a key for one environment, add `?environment=development` or `?environment=production`. ## Next steps * [Agent tools](/user-guide/agents/agent-tools): add and manage tools on an Agent. * [Runtime tools](/user-guide/tools/runtime-tools): tool ID syntax for API and SDK builds. * [GitHub integration](/user-guide/integrations/github-integration): connect GitHub for repository and issue workflows. * [Granola integration](/user-guide/integrations/granola-integration): connect Granola and use meeting notes in Agents and Flows.