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.
Quickstart
Section titled “Quickstart”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.
npm install -g @keryn/mcpkeryn-mcp --version0.1.1keryn-mcp tools | grep -c keryn_15curl -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_whoamikeryn_cloud_ai_attributionkeryn_cloud_creditskeryn_cloud_limitskeryn_cloud_start_scankeryn_cloud_get_scankeryn_cloud_cancel_scankeryn_cloud_run_scankeryn_cloud_list_resultsA tool call needs more: the local tools need the Keryn CLI, and the keryn_cloud_* tools need a credential (see Authentication).
Install
Section titled “Install”npm install -g @keryn/mcp # the thin MCP clientclaude 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": "..." } } } }Authentication
Section titled “Authentication”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.
Hosted
Section titled “Hosted”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.
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.
Streamable HTTP, self-run
Section titled “Streamable HTTP, self-run”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.
Limits
Section titled “Limits”- 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/mcp0.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 (401authentication_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_scanreturns at mostmaxFindingsfindings, 25 by default, and setstruncatedwhen 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.
keryn_scan
Section titled “keryn_scan”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. Defaulttrue.maxFindings(optional): Most findings to return. Default25.
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: objectcoverage: objectfindings: Most severe first, up to maxFindings.truncated: true when more findings exist than were returned.
Example, scan the current project.
{"path":"."}keryn_ai_bom
Section titled “keryn_ai_bom”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. Default100.
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":"."}keryn_explain_rule
Section titled “keryn_explain_rule”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"}keryn_mcp_inventory
Section titled “keryn_mcp_inventory”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. Defaultfalse.
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: objectcoverage: objectfindings: Most severe first, up to maxFindings.truncated: true when more findings exist than were returned.
Example, try it on the demo server.
{"example":true}keryn_ai_attribution
Section titled “keryn_ai_attribution”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. Default20000.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":"."}keryn_decide
Section titled “keryn_decide”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":"."}keryn_docs
Section titled “keryn_docs”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"}keryn_cloud_whoami
Section titled “keryn_cloud_whoami”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.
{}keryn_cloud_ai_attribution
Section titled “keryn_cloud_ai_attribution”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>"}]}}keryn_cloud_credits
Section titled “keryn_cloud_credits”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?
{}keryn_cloud_limits
Section titled “keryn_cloud_limits”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?
{}keryn_cloud_start_scan
Section titled “keryn_cloud_start_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. Default10.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}keryn_cloud_get_scan
Section titled “keryn_cloud_get_scan”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"}keryn_cloud_cancel_scan
Section titled “keryn_cloud_cancel_scan”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"}keryn_cloud_run_scan
Section titled “keryn_cloud_run_scan”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. Defaultfalse.
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"}keryn_cloud_list_results
Section titled “keryn_cloud_list_results”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?
{}The demo server
Section titled “The demo server”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 addressnotes (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.