# Kernel MCP

Connect your AI agent to [Kernel](https://kernelcode.io), the verification layer for onchain software. Your agent can scan a GitHub repository or a Robinhood Chain contract before it ships, trades or integrates, and get back a score, a verdict and a step-by-step fix plan as JSON.

Paid tools are pay per call with [x402](https://x402.org), in USDG on Robinhood Chain. There is no account, API key or subscription, and a call that fails is never charged.

```
https://mcp.kernelcode.io/mcp
```

This repo has the config for popular MCP clients, a small TypeScript client that pays for you, and runnable examples. The Kernel service itself is closed source; the [attestation contract](https://github.com/kernelcode-labs/KernelAttestations-contract) is public.

## Tools

| Tool | What it does | Price |
|---|---|---|
| `scan_repository` | Public GitHub repo: vulnerable dependencies (OSV.dev), leaked secrets, GitHub Actions risks, Solidity patterns | $0.05 |
| `scan_contract` | Deployed Robinhood Chain contract: proxies and upgradeability, privileged functions, ownership, dangerous opcodes, verified source | $0.10 |
| `analyze_dependencies` | Lockfiles only, with the version to upgrade each package to | $0.02 |
| `prove_property` | Formal verification of C or Verilog with Aristotle by Harmonic: each property proved, refuted or unresolved, plus the proof archive. Asynchronous: returns a `scan_id` to follow with `get_verification` | $0.05 + your Aristotle credits |
| `attest_verification` | Signs a report so your wallet can publish its hash to KernelAttestations onchain | $0.02 + your gas |
| `get_verification` | Status, score, plan and findings for any `scan_id`, and live progress while a proof runs | Free |
| `kernel_info` | Prices, accepted networks and tokens, payment recipient | Free |

Scans read code and bytecode only. They never execute it, and a clean scan is a scan, not a formal proof. For a proof, use `prove_property`: it runs on your own [Aristotle](https://aristotle.harmonic.fun) API key (pass `aristotle_api_key`, or save it once in the Kernel app under API keys).

## Add it to your agent

**Claude Code**

```bash
claude mcp add --transport http kernel https://mcp.kernelcode.io/mcp
```

**Cursor** (`.cursor/mcp.json`)

```json
{ "mcpServers": { "kernel": { "url": "https://mcp.kernelcode.io/mcp" } } }
```

VS Code, Claude Desktop, Windsurf, Codex and stdio-only clients are in [`clients/`](clients/README.md).

Any of these can use the free tools straight away. For the paid tools, the client has to answer the x402 payment request, which most editors don't do yet. The TypeScript client below does.

## Paying with x402

1. Your agent calls a paid tool.
2. Kernel replies with a payment request: the amount in USDG, the recipient and the network.
3. The client signs a USDG transfer authorization (EIP-3009) from your wallet and calls again with it attached.
4. Kernel runs the tool. Only if it succeeds is the payment settled onchain, and the receipt comes back with the result.

Your wallet needs USDG on Robinhood Chain (chain `4663`, token `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`). It does not need ETH for these payments; the facilitator pays that gas. Only `attest_verification` asks your wallet to send a transaction itself.

### USDG must be allowed explicitly

x402 clients only pay in a short list of default tokens, and USDG is not on it. Without an allowlist entry, every payment is refused on the client side before anything is signed. Add it with a cap:

```ts
import { createx402MCPClient } from '@x402/mcp';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { privateKeyToAccount } from 'viem/accounts';

const wallet = privateKeyToAccount(process.env.KERNEL_PRIVATE_KEY as `0x${string}`);

const kernel = createx402MCPClient({
  name: 'my-agent', version: '1.0.0',
  schemes: [{ network: 'eip155:4663', client: new ExactEvmScheme(wallet) }],
  spendControls: {
    allowedAssets: [{
      network: 'eip155:4663',
      asset: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168', // USDG
      maxAmountPerPayment: '200000',                         // 0.20 USDG (6 decimals)
    }],
  },
  autoPayment: true,
});
await kernel.connect(new StreamableHTTPClientTransport(new URL('https://mcp.kernelcode.io/mcp')));

const result = await kernel.callTool('scan_contract', { address: '0x…' });
console.log(result.content[0]); // "0x…: 74/100 (grade C). …" followed by the JSON report
```

[`src/kernel.ts`](src/kernel.ts) wraps this as `connectPaid()`, plus `connectFree()` and helpers to read results.

## Examples

```bash
git clone https://github.com/kernelcode-labs/kernel-mcp && cd kernel-mcp
npm install
cp .env.example .env   # add KERNEL_PRIVATE_KEY for the paid examples
```

| Command | Cost | What it shows |
|---|---|---|
| `npm run free` | Free | List tools and prices; add a `scan_id` to fetch that report |
| `npm run scan:contract -- 0x…` | $0.10 | Scan a contract and print the action plan and payment tx |
| `npm run scan:repo -- owner/repo` | $0.05 | Scan a repo and list findings with fixes; add `--deps` for the $0.02 dependency check |
| `npm run gate -- owner/repo` | $0.05 | Exit non-zero below `MIN_GRADE` (default B) or on any critical finding. Use it before a deploy step |
| `npm run rest -- owner/repo` | $0.05 | The same scan over plain HTTP 402 with `@x402/fetch`, no MCP |
| `npm run prove -- --demo` | $0.05 + Aristotle credits | Prove a small C function with Aristotle and follow the run to its verdicts. Needs `ARISTOTLE_API_KEY` |
| `npm run attest -- scan_…` | $0.02 + gas | Get Kernel's signature and send `attest()` from your wallet |

Use a dedicated wallet that holds only what you plan to spend. `KERNEL_MAX_USD` caps any single payment (default $0.20).

## What comes back

Every scan tool returns the same shape as `get_verification`:

```jsonc
{
  "scan_id": "scan_…",
  "target": "owner/repo@<commit>",
  "score": 74,                 // 0-100, capped by the worst open severity
  "grade": "C",
  "verdict": "Not ready to ship: 1 high severity issue to fix first",
  "summary": "…what was checked, what wasn't",
  "severity_counts": { "critical": 0, "high": 1, "medium": 2, "low": 4, "info": 1 },
  "categories": [{ "area": "Dependencies", "status": "issues", "score": 60, "note": "…" }],
  "action_plan": [{ "step": 1, "priority": "now", "title": "…", "detail": "…", "items": ["pkg 1.2.3 → 1.2.9"] }],
  "top_findings": [{ "id": "dep-1", "severity": "high", "title": "…", "location": { "path": "package-lock.json" }, "recommendation": "…" }],
  "report_hash": "0x…",        // sha256 of the canonical report; what gets attested
  "public_url": null,          // set once the report is made public or attested
  "attestations": []
}
```

Pass `detail: "full"` to `get_verification` for the complete report with evidence.

## REST

The paid tools are also plain HTTP endpoints that answer with `402 Payment Required`. They accept GET with query parameters or POST with JSON:

| Endpoint | Body |
|---|---|
| `POST https://app.kernelcode.io/api/x402/scan/repository` | `{ "repository": "owner/repo", "ref"?: "main" }` |
| `POST https://app.kernelcode.io/api/x402/scan/contract` | `{ "address": "0x…", "chain_id"?: 4663 }` |
| `POST https://app.kernelcode.io/api/x402/scan/dependencies` | `{ "repository": "owner/repo" }` |
| `POST https://app.kernelcode.io/api/x402/attest` | `{ "scan_id": "scan_…", "attester": "0x…" }` |
| `POST https://app.kernelcode.io/api/x402/prove` | `{ "language": "c", "specification": "…", "repository"?: "owner/repo", "path"?: "src", "files"?: [{ "path", "content" }], "aristotle_api_key"?: "arstl_…" }` |
| `GET https://app.kernelcode.io/api/x402/scans/:id` | Free |
| `GET https://app.kernelcode.io/api/x402` | Free: prices and networks |

## Links

- Site: [kernelcode.io](https://kernelcode.io) · Tools and pricing: [kernelcode.io/tools](https://kernelcode.io/tools)
- App: [app.kernelcode.io](https://app.kernelcode.io)
- Attestation contract: [kernelcode-labs/KernelAttestations-contract](https://github.com/kernelcode-labs/KernelAttestations-contract)
- X: [@useKernelCode](https://x.com/useKernelCode)

## License

MIT