@diegotsi/flint-mcp

MCP (Model Context Protocol) server for Flint — triage, analyze, and fix your bug reports straight from Claude Code, Cursor, Claude Desktop, or any MCP client.

Quick start

1. Get a personal access token — a flint_pat_… string (step 1 below).
2. Add the MCP to your client with that token (step 2 below).
3. Ask away — "list my P1 bugs", "what's the root cause of bug clxx123", "open a PR for the suggested fix".

1. Get a token

The MCP authenticates as you, with a personal access token — not the shared admin key. So actions are scoped to your account and role, and show up in the audit log under your name.

1. Open the Flint admin dashboard and sign in.
2. Go to Settings → Team → Personal Access Tokens.
3. Click New token, give it a name (e.g. My laptop MCP), optionally pick an expiry, and Create.
4. Copy the token now (flint_pat_…) — it's shown once and stored only as a hash. If you lose it, just create another.

Tokens are revocable any time from the same screen (they show their last-used time), so create one per machine and revoke it if a laptop is lost.

Self-hosting without user accounts? You can fall back to the server's shared FLINT_ADMIN_KEY (god-mode across every project). Prefer a per-user token whenever you have one.

2. Add the MCP

You'll also need:

• FLINT_SERVER_URL — your Flint API URL, e.g. https://api.yourflint.com.
• FLINT_PROJECT_ID (optional) — a default project so you don't pass projectId on every call. Find it in the project's URL in the dashboard.

Claude Code

claude mcp add flint \
  -e FLINT_SERVER_URL=https://api.yourflint.com \
  -e FLINT_API_TOKEN=flint_pat_your_token \
  -e FLINT_PROJECT_ID=your-project-id \
  -- npx -y @diegotsi/flint-mcp

Cursor / Windsurf / Claude Desktop

Add to your MCP config (.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, or claude_desktop_config.json):

{
  "mcpServers": {
    "flint": {
      "command": "npx",
      "args": ["-y", "@diegotsi/flint-mcp"],
      "env": {
        "FLINT_SERVER_URL": "https://api.yourflint.com",
        "FLINT_API_TOKEN": "flint_pat_your_token",
        "FLINT_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Restart the client (or reload the MCP servers) and Flint's tools become available.

Verify / alternatives

npx fetches and runs the published package on demand — there's no separate install step. To confirm it works, run it once with no env; it tells you what's missing and exits, which means it fetched and launched fine:

npx -y @diegotsi/flint-mcp
# → [Flint MCP] Set FLINT_API_TOKEN (per-user, recommended) or FLINT_ADMIN_KEY

Prefer a pinned global binary instead of npx? Install once and point command at it:

npm i -g @diegotsi/flint-mcp   # then use "flint-mcp" as the MCP command

3. Use it

Once connected, ask your assistant things like:

• "List the open P1 bugs in this project."
• "Show me bug clxx123 — root cause and suggested fix."
• "Triage bug clxx123: assign it to me, set severity P2."
• "Open a GitHub PR with the suggested fix for clxx123."
• "What's our bug volume and SLA this week?"

Available tools

| Tool | Description | |---|---| | list_bugs | List bug reports with filters (status, severity, release, …) | | get_bug | Full report detail — AI root cause, console logs, environment | | search_code | Search the indexed codebase (not yet available via MCP) | | suggest_fix | AI-generated fix suggestion for a bug | | triage_bug | Set assignee, severity, area or notes | | resolve_bug | Mark a bug as resolved | | create_fix_pr | Open a GitHub PR with an AI-generated fix | | get_analytics | Project analytics (volume, severity, releases, SLA) | | chat_about_bug | Ask questions about a bug with full AI context |

Configuration reference

| Env var | Required | Description | |---|---|---| | FLINT_SERVER_URL | yes | URL of your Flint server, e.g. https://api.yourflint.com | | FLINT_API_TOKEN | yes* | Recommended. Per-user personal access token (flint_pat_…) from Settings → Team → Personal Access Tokens. Scoped to your account, revocable, and audited. | | FLINT_ADMIN_KEY | yes* | Shared admin key (X-Admin-Key) — god-mode across all projects. Use only when a per-user token isn't available. | | FLINT_PROJECT_ID | no | Default project — avoids passing projectId on every call |

* Provide either FLINT_API_TOKEN (preferred) or FLINT_ADMIN_KEY. The token takes precedence. FLINT_API_KEY is still accepted as a fallback for FLINT_ADMIN_KEY.

Troubleshooting

• 401 / Unauthorized — the token is wrong, expired, or revoked. Create a fresh one under Settings → Team → Personal Access Tokens. If you set both vars, FLINT_API_TOKEN wins over FLINT_ADMIN_KEY.
• projectId is required — set FLINT_PROJECT_ID, or pass projectId in the request.
• Nothing happens / tools missing — confirm FLINT_SERVER_URL points at your Flint API and that the client was restarted after editing its MCP config.

Development

bun run dev    # run from source (tsx)
bun run build  # bundle to dist/ (tsup)

Tests live in src/tools/mcpTools.test.ts and run via the root vitest workspace (bunx vitest run --project mcp).