@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

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 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:

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.