# Keryn MCP

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> The Keryn MCP server (@keryn/mcp): install it, authenticate, and what each of its tools takes and returns. Also the deliberately flawed demo server.

Source: https://keryn.dev/docs/reference/mcp-tools/

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](https://keryn.dev/download/#mcp).

## 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.

```sh
npm install -g @keryn/mcp
```

```sh
keryn-mcp --version
```

```text
0.1.1
```

```sh
keryn-mcp tools | grep -c keryn_
```

```text
15
```

```sh
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")'
```

```text
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](#authentication)).

## Install

```sh
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](https://keryn.dev/docs/start/install/), 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:

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

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

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.

```sh
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](https://keryn.dev/docs/reference/api/) document as `POST /mcp`.

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

- 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](#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.

## Tools

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](https://keryn.dev/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

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.

```json
{"path":"."}
```

### 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. 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?

```json
{"path":"."}
```

### 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?

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

### 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 (&#123;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.

```json
{"example":true}
```

### 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. 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?

```json
{"path":"."}
```

### 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?

```json
{"path":"."}
```

### 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?

```json
{"topic":"exit-codes"}
```

### 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.

```json
{}
```

### 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.

```json
{"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

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?

```json
{}
```

### 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?

```json
{}
```

### 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. 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.

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

### 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?

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

### 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.

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

### 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. 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.

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

### 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?

```json
{}
```

## 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.

> **Caution: Deliberately flawed**
> One tool has a poisoned description, one is over-broad, one is clean. They carry no safety annotations on purpose. Do not copy them.

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