Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Keryn MCP

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    Keryn ships an MCP server, @keryn/mcp: 16 tools that scan code on your machine, list its AI bill of materials, explain a rule, propose a release decision, judge another MCP server, and work with Keryn Cloud. Registry name io.github.getkeryn/mcp. Protocol versions 2025-06-18, 2025-03-26, 2024-11-05; transports stdio and streamable HTTP. Version 0.1.1, the one on npm, has 15 of the 16 tools.

    For npm and MCP registry availability, see Download.

    This runs with Node.js 20 or newer and nothing else: no Keryn CLI, no account and no key. It installs the server, lists the tools of the installed version, then asks the hosted endpoint for its tool list, which needs no credential.

    Terminal window
    npm install -g @keryn/mcp
    Terminal window
    keryn-mcp --version
    0.1.1
    Terminal window
    keryn-mcp tools | grep -c keryn_
    15
    Terminal window
    curl -s https://api.keryn.app/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).result.tools.map((t) => t.name).join("\n")'
    keryn_cloud_whoami
    keryn_cloud_ai_attribution
    keryn_cloud_credits
    keryn_cloud_limits
    keryn_cloud_start_scan
    keryn_cloud_get_scan
    keryn_cloud_cancel_scan
    keryn_cloud_run_scan
    keryn_cloud_list_results

    A tool call needs more: the local tools need the Keryn CLI, and the keryn_cloud_* tools need a credential (see Authentication).

    Terminal window
    npm install -g @keryn/mcp # the thin MCP client
    claude mcp add keryn -- keryn-mcp # Claude Code (local and cloud tools)

    The local tools run the Keryn CLI on your machine. The CLI is not on npm: get it from the install page, which says how each build is distributed. The keryn_cloud_* tools need only the client and an account.

    Other clients take a command and no arguments:

    { "mcpServers": { "keryn": { "command": "keryn-mcp", "env": { "KERYN_API_KEY": "..." } } } }

    The local tools need none and send nothing anywhere. The keryn_cloud_* tools use one credential, in this order: KERYN_API_KEY (an organization API key), KERYN_WORKER_TOKEN, or the device token stored by keryn-mcp pair (approve the code in Keryn Cloud; the token is stored with mode 0600). KERYN_ORGANIZATION pins the organization: calls fail with organization_changed if the credential belongs to another. Start with keryn_cloud_whoami.

    Keryn runs the cloud tools for you at https://api.keryn.app/mcp (streamable HTTP, JSON answers). The handshake and the tool list need no credential; every tool call needs your organization API key, and runs as that key: its organization, its scopes, its project limits, its rate limits.

    Terminal window
    claude mcp add --transport http keryn https://api.keryn.app/mcp --header "Authorization: Bearer $KERYN_API_KEY"

    A paired device token works too (x-keryn-worker-token), and x-keryn-organization: <id> pins the organization: a call fails with organization_changed if the credential belongs to another. A browser session cookie is never accepted, a request from a foreign Origin is refused, bodies are limited to 64 KiB, and the per-address ingress limit and the per-organization limits apply (429 with retry-after). Only the keryn_cloud_* tools are hosted: the local tools read your files, so they stay in the stdio server. The endpoint is in the Cloud API document as POST /mcp.

    keryn-mcp --http --port 8787 serves the same endpoint on loopback. Every request brings its own credential (Authorization: Bearer <key> or x-keryn-worker-token, plus x-keryn-organization); a request without one gets no cloud access, never the server operator’s. Local tools are off over HTTP unless you pass --allow-local-tools, and a browser origin other than loopback is refused unless you pass --allow-origin.

    • The package contains no scanner and no rules. The local tools start the Keryn CLI, which is not on npm. Without it, a local tool answers with a tool error that says where to get it.
    • @keryn/mcp 0.1.1, the version on npm, has 15 of the 16 tools below. The Tools table marks the others, which are on main and not published yet.
    • The keryn_cloud_* tools need a credential. Without one, a call answers with a tool error that says how to sign in.
    • The hosted endpoint serves only the keryn_cloud_* tools. It answers the handshake and the tool list without a credential, and refuses a tool call without one (401 authentication_required).
    • The hosted endpoint limits a request body to 64 KiB.
    • Over HTTP the server binds to loopback by default, and the local tools are off unless you pass --allow-local-tools.
    • keryn_scan returns at most maxFindings findings, 25 by default, and sets truncated when there are more.
    • The demo server refuses tools/call. It exists to be scanned.

    This table describes main. keryn_cloud_ai_attribution is not in @keryn/mcp 0.1.1, the version on npm.

    Tool Runs What it does
    keryn_scan local Scan a folder for AI security findings
    keryn_ai_bom local List the AI components of a folder (AI-BOM)
    keryn_explain_rule local Explain a Keryn rule
    keryn_mcp_inventory local Judge an MCP server’s tools for risk
    keryn_ai_attribution local Find AI coding tool use in a repository
    keryn_decide local Propose a release decision
    keryn_docs local Read Keryn’s offline docs
    keryn_cloud_whoami cloud Show who Keryn Cloud thinks you are
    keryn_cloud_ai_attribution (hosted only, not in 0.1.1) cloud Analyse AI attribution from commit metadata
    keryn_cloud_credits cloud Show Keryn Cloud credit
    keryn_cloud_limits cloud Show Keryn Cloud limits and price
    keryn_cloud_start_scan cloud Start a Keryn Cloud trust scan
    keryn_cloud_get_scan cloud Get a Keryn Cloud scan
    keryn_cloud_cancel_scan cloud Cancel a Keryn Cloud scan
    keryn_cloud_run_scan cloud Run a Keryn Cloud trust, surface or MCP scan
    keryn_cloud_list_results cloud List uploaded scan results

    Every tool has an input schema, an output schema, behaviour annotations and an example; keryn-mcp tools --json and /mcp/tools.json carry them in full. Results come back as structuredContent matching the output schema, with the same JSON as text. Failures are tool errors (isError), never protocol errors, and say what to do.

    Scan a folder or file on this machine with Keryn: finds the AI models, SDKs, agents, prompts, tools and MCP servers it uses and where they are exposed, with the proof level of each finding. Runs offline. Returns the exit code, counts, coverage and the most severe findings; pass a ruleId to keryn_explain_rule.

    read-only, idempotent, local only.

    Input:

    • path: Folder or file to scan.
    • failOn (optional): Lowest severity that makes the exit code 1. Default "error".
    • deep (optional): Also run the Deep pass (interprocedural analysis). Slower; finds chains across files. Default true.
    • maxFindings (optional): Most findings to return. Default 25.

    Returns:

    • assessment (optional): Recorded canonical cases, decision reasons and accounting from keryn.dev/assessment/v1. Case counts are separate from raw findings.
    • exitCode: Keryn exit code: 0 pass, 1 findings, 3 incomplete coverage, 10 warnings.
    • counts: object
    • coverage: object
    • findings: Most severe first, up to maxFindings.
    • truncated: true when more findings exist than were returned.

    Example, scan the current project.

    {"path":"."}

    Inventory the AI components of a folder or file on this machine as a CycloneDX 1.6 AI bill of materials: models, providers, SDKs, agents, tools, MCP servers. Faster than keryn_scan and returns components, not findings. Runs offline.

    read-only, idempotent, local only.

    Input:

    • path: Folder or file to inventory.
    • maxComponents (optional): Most components to return. Default 100.

    Returns:

    • specVersion: CycloneDX version, 1.6.
    • componentCount: All components found.
    • components: Up to maxComponents.
    • truncated: true when more components exist than were returned.

    Example, which AI libraries does this repo use?

    {"path":"."}

    Explain one Keryn rule from its id: what it reports, severity, confidence, false-positive risk, the trust edge it sits on, CWE and OWASP mappings, remediation and references. Offline; reads the rules bundled with the CLI.

    read-only, idempotent, local only.

    Input:

    • ruleId: Rule id, for example keryn.agentclient.codex-sandbox-full-access.

    Returns:

    • id: Rule id.
    • severity: ERROR, WARNING or INFO.
    • message: What the rule reports.
    • confidence (optional): P0 to P3.
    • edge (optional): The trust edge: reaches, calls, reads, writes, sends, grants, depends_on, trusts or none.
    • details: Everything else the CLI prints: taxa, remediation, references.

    Example, why was this flagged?

    {"ruleId":"keryn.agentclient.codex-sandbox-full-access"}

    Judge the tools of an MCP server from a saved tools/list response: permissions, side effects, risk score and a poisoning screen over names and descriptions (hidden text, instructions to read secrets, cross-tool shadowing). The server is never contacted. Set example to judge Keryn’s deliberately flawed demo server.

    read-only, idempotent, local only.

    Input:

    • toolsList (optional): A tools/list response ({tools: […]}) or an array of tool definitions.
    • example (optional): Judge the Keryn demo MCP server’s tool list instead. Default false.

    Returns:

    • assessment (optional): Recorded canonical cases, decision reasons and accounting from keryn.dev/assessment/v1. Case counts are separate from raw findings.
    • exitCode: Keryn exit code: 0 pass, 1 findings, 3 incomplete coverage, 10 warnings.
    • counts: object
    • coverage: object
    • findings: Most severe first, up to maxFindings.
    • truncated: true when more findings exist than were returned.

    Example, try it on the demo server.

    {"example":true}

    Find where AI coding tools are used in a git repository on this machine: tool configuration and instruction files (Copilot, Cursor, Claude Code, Codex, Windsurf, Aider and others) and the commits that declare AI involvement (Co-authored-by and Assisted-by trailers, agent accounts, signature lines, Git AI notes), each with a confidence. Reads commit metadata and file paths only: no diffs, no code leave the machine. Aggregate only: it never breaks results down by developer. Declared involvement is a lower bound and says nothing about lines written.

    read-only, idempotent, local only.

    Input:

    • path: Repository folder.
    • maxCommits (optional): Most commits read, newest first. Default 20000.
    • since (optional): Only commits after this date, for example 2026-01-01 or 6.months.

    Returns:

    • commits: Commits read from the local git history (0 when none could be read).
    • declared: Commits that declare AI involvement at medium or high confidence.
    • declaredShare (optional): declared / commits by people: a lower bound, because use that leaves no mark is not seen. Absent with no commits.
    • tools: Tools the commits declare, most first.
    • configured: Tools the tree is set up for (configuration and instruction files): no code is attributed by these.
    • series: The last 12 months.
    • limits: Always read these with the numbers.

    Example, which AI tools does this repository use, and how often do commits declare them?

    {"path":"."}

    Propose the release decision for a folder: Go, Go with accepted risk, or Hold, from a scan and the repository’s .keryn/decisions.yml. It names what is open and what was accepted; it never says a release is safe, and a person signs it with keryn decide sign.

    read-only, idempotent, local only.

    Input:

    • path: Repository folder.

    Returns:

    • exitCode: 0 Go, 1 Hold, 3 incomplete coverage, 10 warnings.
    • label: Go, Go with accepted risk, or Hold.
    • line: One-line statement of the decision.
    • holds: Open Holds.
    • acceptedRisks: Risks accepted on purpose.
    • signed: The signature record, or null.
    • coverageStatement (optional): What the scan did and did not cover.

    Example, can this be released?

    {"path":"."}

    Read a page of the documentation that ships inside the CLI: command help (cmd-scan, cmd-ci, …), exit codes, output formats, the eight edge kinds. Call with no topic to list the pages.

    read-only, idempotent, local only.

    Input:

    • topic (optional): A page id or a unique prefix, for example exit-codes. Omit to list pages.

    Returns:

    • topic: The page id, or null for the list.
    • text: The page as Markdown, or the list of pages as lines.

    Example, what do the exit codes mean?

    {"topic":"exit-codes"}

    Show the identity behind the Keryn Cloud credential in use: kind (API key, device or user), scopes, project limits and the organization every call is scoped to. Use it first to confirm the organization.

    read-only, idempotent, reaches Keryn Cloud.

    Input: none.

    Returns:

    • kind: user, api-key or worker.
    • organizationId: The organization all calls are scoped to.
    • organizationName (optional): Organization name.
    • scopes: Scopes the credential holds.
    • projectIds: Projects the credential is limited to; null means all.

    Example, confirm the organization.

    {}

    Not in @keryn/mcp 0.1.1. The hosted endpoint has it. Run the stable v1 attribution API on commit metadata you supply. Uses the same request and response as the SDK analyseAttribution method. Sends no source code. Returns organization aggregates, evidence and shadow metering; per-developer rows require a signed-in administrator via HTTP.

    changes state, idempotent, reaches Keryn Cloud.

    Input:

    • body: Attribution request body.

    Returns:

    • report: Stable keryn.ai-attribution/1 report.
    • metering: Shadow attribution metering.

    Example, analyse a synthetic assisted commit without sending source code.

    {"body":{"commits":[{"sha":"0000000000000000000000000000000000000001","authoredAt":"2026-11-01T10:00:00Z","authorName":"Example","authorEmail":"developer@example.invalid","message":"feat: example\n\nCo-authored-by: Claude <noreply@anthropic.com>"}]}}

    Show the organization’s credit: balance, what is reserved by running scans, the part restricted to certain uses, the grants (starter, promo) with their expiry, and whether the starter credit is still available.

    read-only, idempotent, reaches Keryn Cloud.

    Input: none.

    Returns:

    • balanceCents: Balance in cents.
    • reservedCents: Reserved by queued or running scans.
    • restrictedCents (optional): Free-grant credit that cannot pay for every use.
    • starter: available or claimed.
    • grants: Starter and promo grants.

    Example, how much credit is left?

    {}

    Show what the organization may run now: available credit, scans at a time, whether trust scans are enabled, any payment hold, and what a website scan costs: credits per page checked under the published table (a scan is rounded up to a whole credit and unchanged pages are free), or the cents per page a service before that table charges.

    read-only, idempotent, reaches Keryn Cloud.

    Input: none.

    Returns:

    • availableCents: Balance minus reservations.
    • concurrencyLimit: Scans at a time.
    • trustScanEnabled: Trust scans allowed.
    • paymentHold: A hold blocks new work.
    • unitCents (optional): Cents per page, only from a service that predates the published table.
    • creditsPerUrl (optional): Credits per page checked (1 credit is 1 US cent).
    • rounding (optional): How a scan’s total becomes whole credits, and when a repeat is free.
    • maxPages (optional): Most pages per scan.

    Example, can I start a scan?

    {}

    Queue a trust scan of a public website in Keryn Cloud. It reserves credit for maxPages and returns at once; poll keryn_cloud_get_scan. Pass the same idempotencyKey on a retry so credit is never reserved twice. Scans only public addresses.

    changes state, not idempotent, reaches Keryn Cloud.

    Input:

    • url: http or https address, default ports, no credentials in it.
    • maxPages (optional): Pages to scan. Default 10.
    • projectId (optional): Limit to a project.
    • idempotencyKey (optional): Unique per intended scan. Reuse it when retrying.

    Returns:

    • id: Scan id.
    • status: queued, running, completed, failed or canceled.
    • url (optional): The scanned address.
    • maxPages (optional): Page limit.
    • reservedCents (optional): Credit reserved for the scan, in cents.
    • errorCode (optional): Why it failed, if it did.
    • result (optional): The scan result when completed.

    Example, scan a site.

    {"url":"https://example.com","maxPages":10}

    Get a queued, running or finished Keryn Cloud trust scan by id, with its result once completed. Poll every few seconds until status is completed, failed or canceled.

    read-only, idempotent, reaches Keryn Cloud.

    Input:

    • id: Scan id from keryn_cloud_start_scan.

    Returns:

    • id: Scan id.
    • status: queued, running, completed, failed or canceled.
    • url (optional): The scanned address.
    • maxPages (optional): Page limit.
    • reservedCents (optional): Credit reserved for the scan, in cents.
    • errorCode (optional): Why it failed, if it did.
    • result (optional): The scan result when completed.

    Example, is it done?

    {"id":"123e4567-e89b-12d3-a456-426614174000"}

    Ask a queued or running Keryn Cloud scan to stop. Unused reserved credit is released. Safe to repeat.

    destructive, idempotent, reaches Keryn Cloud.

    Input:

    • id: Scan id.

    Returns:

    • cancelRequested: true once the request was accepted.

    Example, stop a scan.

    {"id":"123e4567-e89b-12d3-a456-426614174000"}

    Run a Keryn Cloud scan of a public address and store the result: trust (a site’s privacy, security, legal and AI pages), surface (which AI services a host exposes) or mcp (a remote MCP server’s tools, prompts and resources). Active surface checks need a domain you verified. It answers when the scan is done.

    changes state, not idempotent, reaches Keryn Cloud.

    Input:

    • kind: trust, surface or mcp.
    • target: A URL for trust and mcp, a host name for surface.
    • active (optional): surface only: active port checks on a verified domain. Default false.

    Returns:

    • id: Stored scan id.
    • kind: trust, surface or mcp.
    • target: What was scanned.
    • status: done or failed.
    • findings: Findings in the report.
    • summary (optional): Short typed summary.
    • error (optional): Why it failed.

    Example, profile an MCP server.

    {"kind":"mcp","target":"https://api.keryn.app/demo/mcp"}

    List the scan results the organization uploaded to Keryn Cloud under its sharing setting (100 most recent): repository, visibility, how much was stored, and the counts.

    read-only, idempotent, reaches Keryn Cloud.

    Input: none.

    Returns:

    • results: Uploaded results, newest first.

    Example, what was uploaded?

    {}

    Separate from the server above, Keryn runs a deliberately flawed MCP endpoint so there is something to scan: https://api.keryn.app/demo/mcp, streamable-http (JSON-RPC over POST, JSON answers), protocol 2025-06-18. Static and stateless. initialize, ping and the tools, prompts and resources lists answer with fixed content; tools/call and every other method is refused. It takes no account, no budget and no input, and sets no CORS headers. keryn mcp inventory --example judges the same tool list offline.

    Tool Description Input
    search_notes Search the user’s saved notes by keyword and return matching titles. Read-only. query: Keyword to look for in note titles
    summarize_page Summarize a web page for the user. [hidden instruction removed from this page] url: Page address
    notes (optional): Context for the summary
    run_shell Run any shell command on the host with the full privileges of the user: read, write and delete any file, open network connections, install software and change system settings. command: The command line to execute

    Prompts: explain_findings. Resources: keryn-demo://about. tools/call is refused.