flintai-mcp

A local MCP server (stdio) that gives a coding agent read-only access to a Flint AI backend's AI-SPM issues, inventory, and remediation guidance so it can fix the flagged code.

It is a thin, authenticated REST client over the Flint AI API — no scanner runs locally and no backend changes are required. Everything valuable (AI-reasoned findings, rule-based issues, public-asset vuln enrichment, remediation guidance) is already computed server-side and served over the existing API / static assets.

The package is named for the platform (flintai-mcp) rather than AI-SPM specifically: v1 ships the AI-SPM tools, but it is intended to grow to cover other Flint AI product domains (guardrails, ROI, …) over time.

This repository is generated. flintai-mcp is developed in SandboxAQ's internal monorepo and mirrored here (which also builds and publishes the wheel to PyPI). Please file issues here; see CONTRIBUTING.md to propose changes.

Phase 1: read-only, remote-backed. Fast verification of uncommitted fixes (a local scan + a synchronous backend "dry-run" endpoint) is a planned Phase 2 and is intentionally out of scope here.

Install & run

The idiomatic way is via the published wheel with uvx (no clone, no build step):

uvx flintai-mcp

Configuration

Set two environment variables:

The instance URL is validated against a fail-closed host allowlist before any credential is attached.

The tenant and workspace are auto-discovered from the API key at startup — you do not configure any IDs. A key is pinned to exactly one tenant + active workspace by the backend.

The API key is only ever sent in the Authorization: ApiKey ... header and is never logged.

Wiring into a coding agent

Add to your MCP client config (Claude Code .mcp.json, Cursor, etc.):

{
  "mcpServers": {
    "flintai-mcp": {
      "command": "uvx",
      "args": ["flintai-mcp"],
      "env": {
        "FLINTAI_API_KEY": "sk_...",
        "FLINTAI_INSTANCE": "https://app.flintai.dev"
      }
    }
  }
}

Tools

Fix-focused

• get_context — show the resolved instance / tenant / workspace.
• list_issues(severity?, rule_id?, category?, search?, page_size?, cursor?) — list issues; paginated, page_size capped at 100.
• get_issue(issue_id) — issue detail + assembled rule-level remediation guidance
  • affected objects.
• get_finding_detail(issue_id, object_id, detail_id?) — per-finding file path, code snippet, evidence, and inline remediation.
• find_issues_for_file(path, max_issues?) — issues whose findings reference a given working-tree file (client-side scan; matches by shared path suffix). The scan follows pagination but is bounded — max_issues is capped at 500 and the call at 300 backend requests — and returns a scan block reporting complete, issues_scanned, requests and errors. complete: false means the caps were hit and the file may have findings this result omits; treat it as "unknown", not as "clean", and narrow the search with list_issues filters instead.
• get_remediation_guidance(rule_name) — rule-level remediation markdown.

Inventory browse

• list_models | list_agents | list_tools | list_mcp_servers(name?, severity?, supplier?, library?, page_size?, cursor?)
• get_model | get_agent | get_tool | get_mcp_server(asset_id) — detail plus attached issues, related assets, and code locations.

Remediation guidance

Rule-level remediation markdown has no dedicated API — it is served by the instance's web server as static assets at {instance}/assets/docs-remediations/… (the same origin and files the web UI reads). This server fetches them at runtime over HTTP through the shared client and caches them per session; nothing is bundled into the package. When a rule has no docs (or the assets origin is unreachable), fall back to the per-finding remediation text from get_finding_detail.

For offline development or tests, set FLINTAI_REMEDIATION_DIR to a local directory laid out like the assets (rule-name-to-remediation-folder-map.json + per-rule folders); the loader then reads from disk and never touches the network.

Development

• Layout: src/flintai_mcp/ (src/ layout), tests under test/.
• Editable install: pip install -e '.[dev]', then run flintai-mcp.
• Docs are fetched from your instance at runtime; for offline work point FLINTAI_REMEDIATION_DIR at a local copy of the docs directory.

Tests

pytest

Tests are hermetic (httpx MockTransport for the client and the remediation-docs fetch, a fake client + FLINTAI_REMEDIATION_DIR for the tools), so they need no network or live backend.