QCoda MCP — Developer Setup Guide

Connect your AI coding tool (Claude Code, Cursor, JetBrains, aider) to QCoda so you can manage work items, run analysis pipelines, review concerns, approve builds, and read PM config — without leaving your editor. No QCoda source checkout required.

1. Install

Requires Python 3.11+.

pipx install qcoda-mcp        # recommended — isolated, puts `qcoda-mcp` on PATH
# or
pip install qcoda-mcp
# or run without installing:
uvx qcoda-mcp

Upgrade later: pipx upgrade qcoda-mcp (or pip install -U qcoda-mcp).

2. Get an API key

QCoda dashboard → Profile → copy your qk_… API key.

The key is your QCoda identity and carries your write permissions. Treat it like a password: keep it in an env var / secrets manager, never commit it.

3. Configure your AI tool

All tools use the same two env vars: QCODA_URL and QCODA_API_KEY.

Claude Code

Project-level .mcp.json (this repo only) or user-level ~/.claude/mcp.json (all projects):

{
  "mcpServers": {
    "qcoda": {
      "command": "qcoda-mcp",
      "env": {
        "QCODA_URL": "https://app.qcoda.com",
        "QCODA_API_KEY": "qk_your_key_here"
      }
    }
  }
}

If qcoda-mcp isn't on PATH (e.g. you used plain pip in a venv), use: "command": "python", "args": ["-m", "qcoda_mcp"].

Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json) — same mcpServers block shape.

JetBrains (AI Assistant / MCP) & aider

Point the tool's MCP config at command qcoda-mcp with the same two env vars. For aider, the bundled CLI wrapper also works: qcoda-mcp exposes the tools over stdio.

Restart the tool after editing config. You should see the QCoda tools appear.

4. Project & context scoping

Most tools auto-detect which QCoda project + context you mean from your git repo: matching your current branch against a context's base branch.

• On a branch that matches a QCoda context's base branch → auto-selected.
• No match → pass project="<id>" (and context="<id>") explicitly to the tool.

Find ids with list_scopes (lists your org's projects + contexts).

5. Verify

In your AI tool, ask it to run list_work_items. If you get items back (or "No work items found" for an empty project), you're wired. get_pm_config shows a project's PM integration settings (secrets redacted).

6. What you can do (tool groups)

• Work items: list_work_items, create_work_item, clarify_work_item, get_spec, link_work_items, list_work_item_relations
• Pipeline: get_pipeline_status, get_run_history, get_agent_report, restart_analysis, resume_from_agent, retry_intake, clear_error
• Quality: get_concerns, resolve_concern, approve_for_build, trigger_qc
• PM config: get_pm_config, set_pm_config (non-secret keys only)
• Ledger Q&A: ask_qcoda, ledger_status, list_scopes

Write actions require your account to have write permission (PRODUCT/TECHNICAL role). OBSERVER accounts get read-only and a clear refusal on writes.

7. Troubleshooting

Maintainers: publishing + versioning lives in docs/qcoda_mcp_publishing.md.