hakira-mcp

A local stdio MCP server that lets your coding agent (Claude Code, Cursor, Windsurf, …) trigger Hakira cloud security audits of the repo you're working in — and read the findings back — without leaving the editor.

It exposes eight tools and one resource:

| Tool | Cost | What it does | |---|---|---| | start_audit | spends credits | Upload the project (gitignore-respecting, secrets stripped) and start a background cloud audit. scope:"project" audits everything (at ref if given); scope:"changes" audits only what changed — uncommitted work, a commit (ref:"HEAD"), or a branch (ref:"<branch>", or base for a custom range) — with the diff computed from your local git and shipped as .hakira-changes.patch. Returns { audit_id, status, agent_instruction } immediately. | | get_audit_status | free | Check an audit: queued → provisioning → running → ready (or canceled / error), with credits_used. Project-scope audits also carry estimate.full_project_credits_max — an upper bound for a whole-project audit, not a price. | | get_audit_events | free | Activity trail (coalesced assistant text, collapsed tool runs, progress, findings). No tool result bodies. Use when checking what Hakira is doing / has done. Omit after for the latest page. | | get_audit_findings | free | Finding summaries only. Then call get_finding for critical/high or when explaining/fixing. | | get_finding | free | Full finding (description, evidence, recommendation). Use after get_audit_findings. | | list_audits | free | Recent audits/sessions across your account (is_current marks this local project). Optional workspace_id filter. | | list_workspaces | free | All workspaces on your account; is_current marks this local project (current_workspace_id is null until the first audit creates one). | | cancel_audit | free | Request cancellation of a running audit. |

Resource hakira://finding/<id> returns the same full detail as get_finding (kept for hosts that prefer resources).

⚠️ start_audit spends credits — it's the only Hakira tool that does; the other seven are free. A changes audit usually costs much less than a whole-project audit. If your credit balance is too low the call fails immediately with a payment_required error carrying a top-up link, and nothing is uploaded — add credits and re-run.

Quickstart

1. Add the server to your client config (see Install below) — browser login, no token. On Cursor, Add to Cursor is faster than pasting the prompt.
2. Restart the client so it launches the server (MCP config loads at start; no hot reload). On Cursor after one-click install, toggle/enable in MCP settings is often enough.
3. Ask your agent to run an audit — the first tool call opens your browser to authorize.
4. Read the findings back in your editor.

Give this to your coding agent

Paste this into your coding agent and it will set Hakira up and run your first audit — pasting it is your go-ahead for that one paid call. On Cursor, prefer Add to Cursor (Install) for the install step, then paste this to run the first audit:

Set up the Hakira security-audit MCP server for this project and run a first audit.

Full setup docs for agents: https://hakira.io/mcp.md — read them if you can fetch URLs.

1. Install the server in the coding agent you are running in (work out which one
   that is). Prefer the client's CLI when it has one, otherwise merge a "hakira"
   entry into its MCP config — never overwrite other servers:
   - Claude Code:  claude mcp add hakira -- npx -y hakira-mcp
   - Codex:        codex mcp add hakira -- npx -y hakira-mcp
   - VS Code:      .vscode/mcp.json, under "servers" (not "mcpServers")
   - Cursor:       .cursor/mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json
   Any other client: a stdio server named "hakira", command "npx",
   args ["-y", "hakira-mcp"]. JSON form:
   { "mcpServers": { "hakira": { "type": "stdio", "command": "npx", "args": ["-y", "hakira-mcp"] } } }
   Do not run "npx -y hakira-mcp" in a terminal — it is a server, not an installer.
   Then tell me to restart so the server loads.

2. After I restart, call the Hakira `start_audit` tool — it is the only Hakira
   tool that spends credits, and asking you to run this audit is my go-ahead.
   Pick the scope from what I asked for, and audit the whole project if I didn't say:
   - whole project → scope:"project" (at a branch: add ref:"<branch>")
   - only changes → scope:"changes": no ref = my uncommitted work,
     ref:"HEAD" = my last commit, ref:"<branch>" = everything that branch adds
   Hakira computes the diff from my local git, so don't list files yourself.
   The first call will open my browser to authorize this machine.
   - If start_audit returns a `payment_required` error, show me the buy_credits_url
     from that error and stop — I need to add credits before the audit can run.

3. It returns an audit_id and runs in the background. For this first audit, wait
   for the result: call `get_audit_status` every poll_after_ms until status is
   "ready" (stop on "canceled" or "error"). `credits_used` is what it has spent;
   an `estimate` is only an upper bound for a whole-project audit, not the price
   of this one — don't stop the audit over it.

4. Then call `get_audit_findings` for that audit_id. Summarize the findings by
   severity. For any high/critical, call `get_finding` and show me the evidence
   and recommended fix. If there are no findings, tell me the audit came back clean.

Install

The server runs via npx — no global install needed. Browser login is the default (no token in config): the first tool call opens your browser to authorize this machine, then caches a credential in ~/.hakira/credentials.json (chmod 600).

Cursor (one-click)

Prefer Cursor’s official install deeplink (browser-login config, no token):

Add to Cursor

Or open the deeplink directly:

cursor://anysphere.cursor-deeplink/mcp/install?name=hakira&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhha2lyYS1tY3AiXX0%3D

Badge (for docs / landing pages):

<a href="https://cursor.com/install-mcp?name=hakira&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhha2lyYS1tY3AiXX0%3D">
  <img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" />
</a>

After install, enable the server in Cursor MCP settings if it appears disabled. Manual .cursor/mcp.json editing is still supported (table below).

| Client | Config file | Fallback-token env syntax | |---|---|---| | Claude Code | .mcp.json (project) or ~/.claude/.mcp.json | ${HAKIRA_TOKEN} | | Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json | ${env:HAKIRA_TOKEN} | | Windsurf | ~/.codeium/windsurf/mcp_config.json (global only) | ${HAKIRA_TOKEN} |

Primary (browser login):

{ "mcpServers": { "hakira": { "type": "stdio", "command": "npx", "args": ["-y", "hakira-mcp"] } } }

Headless / CI (no browser): set a Personal Access Token instead. Mint one from the Hakira dashboard and expose it as HAKIRA_TOKEN — the server uses it directly and never opens a browser:

{
  "mcpServers": {
    "hakira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "hakira-mcp"],
      "env": { "HAKIRA_TOKEN": "${HAKIRA_TOKEN}" }
    }
  }
}

On a headless machine with no HAKIRA_TOKEN, a tool call returns a structured authorization_required message with a URL to open elsewhere — it never hangs.

Commands

• hakira-mcp — run the MCP server (what your client launches).
• hakira-mcp logout — delete the cached credential (~/.hakira/credentials.json).

Configuration (env)

| Var | Default | Purpose | |---|---|---| | HAKIRA_TOKEN | — | Personal Access Token. If set, used directly (fully headless; no browser, no cache). | | HAKIRA_API_URL | https://app.hakira.io/api | Control-Plane API base (Netlify rewrites /api/*→CP). | | HAKIRA_WEB_URL | https://app.hakira.io | App host for human SPA pages (e.g. /billing). |

Privacy — what leaves your machine

start_audit uploads a ZIP of your working tree (honoring .gitignore). It never ships your real .git, and it strips a secret deny-list on top of .gitignore: .env*, *.pem, *.key, id_rsa*, *.p12, *.pfx, .ssh/, .aws/, .npmrc, *.keystore. Add more patterns in a .hakiraignore file at the repo root. Every run prints a one-line manifest (uploading N files / M MB; excluded: …) to stderr and in the tool result, so you see exactly what left the machine before the paid run.

Dev / e2e (local stack)

Build the package, then point a client at the built binary against a local Control Plane:

{
  "mcpServers": {
    "hakira": {
      "type": "stdio",
      "command": "node",
      "args": ["packages/hakira-mcp/dist/index.js"],
      "env": {
        "HAKIRA_API_URL": "http://localhost:3000",
        "HAKIRA_WEB_URL": "http://localhost:5173",
        "HAKIRA_TOKEN": "<dev-seed PAT>"
      }
    }
  }
}

Restart the client session after each rebuild (no mid-session reload). Fast inner loop without a client:

npm run build -w packages/hakira-mcp
npx @modelcontextprotocol/inspector --cli node packages/hakira-mcp/dist/index.js --method tools/list

Develop

npm run build -w packages/hakira-mcp   # tsc → dist/ (+ chmod +x the bin)
npm test  -w packages/hakira-mcp       # unit + stdio smoke (build first for the smoke test)

All logging goes to stderr — stdout is the JSON-RPC channel.