@konsulto/mcp

MCP server that lets Claude Code (and any other MCP-capable client) drive the Konsulto cybersecurity audit platform from the CLI:

• Read — list audits you're on, search findings/templates, read a finding (including body rendered as markdown so the LLM can reason about prose), read a single section.

• Write — compose findings from structured fields (backend builds the Tiptap body), update scalars, append/replace section prose using markdown, bulk-change status with dry-run preview.

• Evidence — upload files/inline content/base64, graft evidence into a finding's body at the right section.

• Scope & assets — list scope, list/create assets, match-or-create an asset and link it to a finding.

Acts as the user, with their role permissions, gated by a per-user MCP token. Three runtime gates: tenant feature flag enabled, role has mcp:use, token not revoked/expired.

Quick start

1. Mint an MCP token in the Konsulto web app

Sign in → Profile → MCP Tokens → New MCP token. Copy the kon_mcp_… value once — it isn't shown again. (Tenant admin must have enabled MCP integration first under Account → API Access.)

2. Save the token locally

mkdir -p ~/.konsulto && chmod 700 ~/.konsulto
cat > ~/.konsulto/credentials <<EOF
token: kon_mcp_REPLACE_WITH_YOUR_TOKEN
endpoint: https://api.konsulto.io
EOF
chmod 600 ~/.konsulto/credentials

Or use the KONSULTO_TOKEN env var if you'd rather not write a file.

3. Tell Claude Code about the server

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "konsulto": {
      "command": "npx",
      "args": ["-y", "@konsulto/mcp"]
    }
  }
}

Verify the wiring:

npx @konsulto/mcp doctor

You should see all green checks.

Folder pinning (optional, recommended)

Run npx @konsulto/mcp init inside an engagement folder to pin it to one audit:

~/audits/acme-q2-pentest/
├── .konsulto.yml          ← pins this folder to one audit
├── recon/
└── notes.md

When Claude Code launches in that folder (or any subfolder), the MCP auto-pins the audit. No more thinking about audit IDs.

The file is sharable with your team — it contains an audit ID and optional endpoint, no secrets.

Workflow patterns

Tools

Every tool is prefixed konsulto_* so it doesn't collide with other MCPs (Burp, nmap, prowler, etc.) you might have configured.

Identity & context

Templates

Findings — read

Findings — write

Evidence

Scope & assets

Helper CLI

The package ships two binaries:

• konsulto-mcp — the stdio MCP server. Claude Code spawns this. You don't run it directly.

• konsulto — interactive helper:

  • konsulto init — write .konsulto.yml for the current folder

  • konsulto whoami — verify token, show identity + permissions + active audit

  • konsulto doctor — sanity-check creds file mode, token validity, network reachability, MCP feature enabled, role has mcp:use

Troubleshooting

konsulto doctor covers each of these explicitly with a one-line fix.

Security model

• Three live gates on every API request: tenant feature flag enabled, your role has mcp:use, your token not revoked/expired. Any of them flipping shuts off MCP traffic immediately — no per-token revocation needed.

• Token storage: ~/.konsulto/credentials (chmod 600) or KONSULTO_TOKEN env. Never in ~/.claude/mcp.json.

• First-time-from-new-IP email: when your token is used from an IP it hasn't been seen on, you get an email so a leak is detectable. The email links to the revoke flow.

• Default expiry: 90 days. Maximum 365.

• Permissions are read live: changing your role propagates within one request — you don't need to re-issue the token.

Multi-engagement on one machine

Set KONSULTO_PROFILE=acme to read ~/.konsulto/credentials.acme instead of the default. Useful when you're contracting on a customer's Konsulto tenant from the same laptop you use for your firm's tenant.

License

MIT — see LICENSE.