@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@latest"]
    }
  }
}

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

Pattern	When to use
Folder-pinned .konsulto.yml	Repeat work on the same engagement. Run konsulto init once per folder.
set_active_audit per session	One workspace, switching audits mentally. Tell Claude "switch to <audit name>".
Explicit per-call	Juggling several audits in one session. Pass audit: to each tool call.

Tools

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

Identity & context

Tool	What it does
konsulto_whoami	Identity, permissions, active audit. Call first in a session.
konsulto_list_my_audits	List audits you're a member of.
konsulto_set_active_audit	Pin one audit for the rest of the session (fuzzy match by name).
konsulto_get_audit_context	One-shot orientation — name, status, scope/asset counts, severity rollup, team.

Templates

Tool	What it does
konsulto_search_templates	Find finding templates by query/severity. Slim shape — id, title, severity, summary, slot names, taxonomy. No body.

Findings — read

Tool	What it does
konsulto_search_findings	Search within an audit (defaults to active).
konsulto_get_finding	Read a finding including its body rendered as markdown so the LLM can reason about prose.
konsulto_read_section	Read just one section of a finding's body as markdown. Cheaper than get_finding for "explain the POC".

Findings — write

Tool	What it does
konsulto_compose_finding	Create from structured fields + optional template + evidence. Backend builds the Tiptap body.
konsulto_update_finding	Change scalar fields (title, severity, status, taxonomy, assets).
konsulto_bulk_update_status	Mass status change. Supports dryRun: true for preview.
konsulto_append_to_section	Add markdown prose to a section. Section names accept aliases (recommendations, mitigation, fix, summary, etc.) — they normalize to canonical keys server-side.
konsulto_replace_section	Replace a section's prose. Old content saved on the audit trail.

Evidence

Tool	What it does
konsulto_attach_evidence	Upload a file path / inline content / base64. Returns an evidenceId.
konsulto_add_evidence_to_finding	Graft an evidenceId into an existing finding's body (auto placement walks poc → description → impact → remediation → end).

Scope & assets

Tool	What it does
konsulto_list_scope	Scope elements for an audit — what's authorized to test.
konsulto_list_assets	Assets in the audit (or tenant-wide).
konsulto_create_asset	Create a host / URL / IAM-role / etc. when a scan reveals one not yet tracked.
konsulto_link_asset	Match-or-create an asset by name and attach it to a finding.

Helper CLI

The same npx @konsulto/mcp command runs as the stdio MCP server when called with no arguments (what Claude Code does), and as an interactive helper when called with a subcommand:

• npx @konsulto/mcp init — write .konsulto.yml for the current folder
• npx @konsulto/mcp whoami — verify token, show identity + permissions
• npx @konsulto/mcp doctor — sanity-check credentials, token, reachability, and configuration

Troubleshooting

Run npx @konsulto/mcp doctor first — it prints a one-line fix for the first failure. For the rest:

Symptom	Fix
No Konsulto credentials found	Set KONSULTO_TOKEN env or create ~/.konsulto/credentials (see Quick start).
Token rejected as the wrong type	You used a non-MCP token. Mint one under Profile → MCP Tokens.
Authentication errors on every call	Token revoked or expired — mint a fresh one.
Permission errors after working previously	Your role or tenant settings changed. Ask an admin.
Loose-permissions warning at startup	chmod 600 ~/.konsulto/credentials

Security

• Treat tokens like passwords. They carry your role's permissions to anyone who holds them. Don't share or commit them.
• Revoke if leaked. Web app → Profile → MCP Tokens. Revocations take effect on the next request.
• Watch your inbox. Konsulto emails you on suspicious token activity — investigate and revoke if you didn't trigger it.
• Verify the package. Published with npm provenance — npm view @konsulto/mcp shows the signature.

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.