ContenoxContenox
Back to Cookbook

Project Planning with Linear MCP

Connect contenox to Linear and let it read your actual codebase, then create grounded tickets — no generic checklists, no copy-paste. Every issue references the real files it found.

What this recipe does: reads next.config.ts and the CI workflow, understands the current deployment setup, lists your Linear teams, then creates one ticket per actionable task — each one pointing at the exact file and line that needs changing.

Setup (one time)

# Register Linear's MCP server (HTTP transport + OAuth)
contenox mcp add linear https://mcp.linear.app/mcp --auth-type oauth

# Authenticate — opens your browser for Linear OAuth
contenox mcp auth linear

Note

Contenox handles the entire OAuth 2.1 flow — dynamic client registration, browser redirect, token exchange, and refresh. After this one step, the token lives in SQLite and rotates automatically forever.

The Chain

MCP tools need to be explicitly allowed in the chain's hooks list alongside local_shell:

cat .contenox/chain-linear-planner.json

{
    "id": "chain-linear-planner",
    "tasks": [{
        "id": "plan",
        "handler": "chat_completion",
        "system_instruction": "You have shell access and Linear via MCP. Read files first, then create grounded issues. Never create generic issues — every issue must reference specific files you actually read.",
        "execute_config": {
            "model": "{{var:model}}",
            "provider": "{{var:provider}}",
            "hooks": ["local_shell", "local_fs", "linear"]
        },
        "transition": {
            "branches": [
                {"operator": "equals", "when": "tool-call", "goto": "run_tools"},
                {"operator": "default", "when": "", "goto": "end"}
            ]
        }
    }, {
        "id": "run_tools",
        "handler": "execute_tool_calls",
        "input_var": "plan",
        "transition": {
            "branches": [{"operator": "default", "when": "", "goto": "plan"}]
        }
    }],
    "token_limit": 65536
}

Recipe: Plan a GCP Cloud Run Deployment

Run this from the root of your repo:

contenox run --chain .contenox/chain-linear-planner.json --shell \
  "Read enterprise/site/next.config.ts and .github/workflows/dockerpublish.yml.
   List your Linear teams. Then create one Linear issue per task needed to
   deploy the enterprise site to GCP Cloud Run. Reference specific files and
   line numbers in each issue description."

What the agent actually did:

  1. cat enterprise/site/next.config.ts → found output: "export" and trailingSlash: true (GitHub Pages config)
  2. cat .github/workflows/dockerpublish.yml → found the Docker build/push steps and the gh-pages deploy action
  3. ls enterprise/site/Dockerfile → not found (missing)
  4. Listed Linear teams → found Development
  5. Created three tickets:
TicketTitleGrounded in
DEV-116Configure Next.js output for Cloud Run deploymentnext.config.ts lines 3-6: output: "export"
DEV-117Adapt Dockerfile for Cloud Run deploymentdockerpublish.yml lines 58-62: runtime-api Docker build step
DEV-118Create Cloud Run service for enterprise sitedockerpublish.yml lines 58-65: GHCR image name

Why It Works

contenox run with --shell gives the model real file access. The Linear MCP gives it real write access to your project tracker. Together, the model doesn't guess — it reads your files and creates issues that a human engineer would write.

The persistent MCP connection means the model's Linear session stays open across all tool calls. If it needed to fetch an issue, update it, and create a child — that's one unbroken conversation with Linear's API, not three separate auth flows.

Adapting This Recipe

Change the prompt to match your team's workflow:

# Plan a database migration
contenox run --chain .contenox/chain-linear-planner.json --shell \
  "Read the schema files in db/migrations/ and create Linear issues for
   migrating from Postgres 14 to 16. One issue per breaking change found."

# Triage a failing test suite
go test ./... 2>&1 | contenox run --chain .contenox/chain-linear-planner.json \
  "Create a Linear bug ticket for each failing test. Include the test name
   and the exact error message in the description."

# Break down a feature from a spec file
cat SPEC.md | contenox run --chain .contenox/chain-linear-planner.json \
  "Read this spec and create Linear issues for each implementation task.
   Use the spec section headers as issue titles."
All recipes