Linear

How to use this skill

This skill is a thin pass-through to Linear's hosted MCP server. The live server is the source of truth for what tools exist, what they're called, what arguments they take, and any per-server instructions Linear publishes.

Always invoke through bash {baseDir}/scripts/invoke.sh — never call mcporter directly. The wrapper seeds the OAuth vault from the env-supplied tokens when needed, then calls mcporter.

Step 1 — Discover the live tool catalog and Linear's own usage instructions. Always run this first; do not rely on tool names from memory:

bash {baseDir}/scripts/invoke.sh list maverick-linear --schema

The output includes Linear's Instructions: field (read it — it specifies, for example, how to format markdown content) and a JSON Schema for every tool's parameters. Treat this as the authoritative reference for the rest of the session.

Step 2 — Call any tool from the catalog using the form \x3Cserver>.\x3Ctool> where \x3Cserver> is maverick-linear (the local registration key, not Linear's announced name):

bash {baseDir}/scripts/invoke.sh call maverick-linear.\x3Ctool> \x3Carg>=\x3Cvalue> ...

Add --output json for structured output (also surfaces transport errors as JSON envelopes):

bash {baseDir}/scripts/invoke.sh call --output json maverick-linear.\x3Ctool> ...

Conventions worth knowing

These hold across most tools but are not contracts — --schema is. Use them as defaults; trust the per-tool schema when it disagrees.

• Upsert pattern. Many write tools accept an optional id: present → updates; absent → creates. Required fields differ between the two cases; the per-tool description in --schema calls this out.
• Linear's own per-server instructions. Read the Instructions: field from the --schema output before formatting any text-content arguments. Linear publishes guidance there (e.g. on markdown formatting) that applies to every applicable tool.
• Linear ID flexibility. Where a parameter is documented as accepting an ID, Linear typically also accepts the human-readable identifier (issue identifiers, project slugs, team names). The schema description is authoritative for each parameter.

Safety

Linear MCP tools split cleanly by name prefix. Read tools (list_*, get_*, search_*, extract_*) are safe to call freely while exploring. Write/delete tools (save_*, delete_*, create_*) modify workspace data visible to the user's team — confirm clear user intent before invoking them.

Authentication

Credentials are available to the agent runtime through required env vars. The wrapper seeds mcporter's vault as needed before each call. mcporter then reads tokens from the vault, sends them with each request, and refreshes them on expiry.

If a call returns HTTP 401 that doesn't recover within a few seconds, the OAuth grant has been revoked — re-authorize the integration.

Data flow

Tool calls travel to Linear's hosted MCP service at https://mcp.linear.app/mcp over HTTPS, authenticated via OAuth. Linear sees the issue/project/comment data referenced by each call. Use this skill for Linear-related work only; do not pass unrelated sensitive content through these tools.