mcp-server-attestation

<!-- studiomeyer-mcp-stack-banner:start -->
> **Part of the [StudioMeyer MCP Stack](https://studiomeyer.io)** — Built in Mallorca 🌴 · ⭐ if you use it
<!-- studiomeyer-mcp-stack-banner:end -->

# mcp-server-attestation


<!-- badges -->
[![npm version](https://img.shields.io/npm/v/mcp-server-attestation?style=flat-square&color=cb3837&logo=npm&label=npm)](https://www.npmjs.com/package/mcp-server-attestation)
[![npm downloads](https://img.shields.io/npm/dm/mcp-server-attestation?style=flat-square&color=cb3837&logo=npm&label=installs%2Fmo)](https://www.npmjs.com/package/mcp-server-attestation)
![License](https://img.shields.io/github/license/studiomeyer-io/mcp-server-attestation?style=flat-square&color=22c55e&label=license)
![Last commit](https://img.shields.io/github/last-commit/studiomeyer-io/mcp-server-attestation?style=flat-square&color=88c0d0&label=updated)
![GitHub stars](https://img.shields.io/github/stars/studiomeyer-io/mcp-server-attestation?style=flat-square&color=ffd700&logo=github&label=stars)
<!-- /badges -->Layer-2 supply-chain hardening for Model Context Protocol servers. Ed25519-signed tool manifests, runtime spawn-attestation, default-deny argument sanitizer.

Direct response to:
- **OX Security marketplace-poisoning, April 2026** — 9 of 11 MCP registries accepted malicious servers. Anthropic's published position: "expected behavior".
- **CVE-2025-69256** — Serverless Framework MCP RCE via `child_process.exec()` command injection.
- **CVE-2025-61591** — Cursor MCP RCE through OAuth-installed malicious server with spawn hijack.

This package provides what Anthropic chose not to: cryptographic verification of which tools a server is allowed to expose and which spawn calls it is allowed to make. It is a drop-in dependency, not a runtime replacement.

## A note from us

We have been building tools and systems for ourselves for the past two years. The fact that this repo is small and has few stars is not because it is new. It is because we only just decided to share what we have built. It is not a fresh experiment, it is a long story with a recent commit.

We love building things and sharing them. We do not love social media tactics, growth hacks, or chasing stars and followers. So this repo is small. The code is real, it gets used, issues get answered. Judge for yourself.

If it helps you, sharing, testing, and feedback help us. If it could be better, an issue is more useful. If you build something with it, tell us at hello@studiomeyer.io. That genuinely makes our day.

From a small studio in Palma de Mallorca.

## Packages (npm workspaces)

| Package | Purpose |
| --- | --- |
| `mcp-server-attestation` (`packages/lib`) | Library: Ed25519 sign/verify, manifest schema, sanitizer, spawn attester, TOFU trust store. |
| `mcp-attest-cli` (`packages/cli`) | CLI `mcp-attest`: `keygen`, `sign`, `verify`, `inspect`, `fingerprint`, `check-pin`. |
| `mcp-attest-demo` (`packages/demo-server`) | Reference MCP server (stdio, spec 2025-06-18) exposing 5 tools that demonstrate the library. |

## Install

```bash
npm install mcp-server-attestation
# CLI:
npm install -g mcp-attest-cli
# Reference MCP server:
npx mcp-attest-demo
```

Node 20+. No external crypto dependencies — uses `node:crypto` Ed25519 primitives.

## Five-line server quickstart

```ts
import { verifyManifestStrict, attestSpawnStrict, type SignedManifest } from "mcp-server-attestation";
import signed from "./signed/manifest.json" assert { type: "json" };

// 1. At startup: prove the manifest you ship is the manifest you signed.
verifyManifestStrict(signed);

// 2. Before every child_process.spawn:
attestSpawnStrict(signed as SignedManifest, { command, args });
```

That is the entire integration. Two function calls, no SaaS, no daemon.

If you would rather re-verify the signature on every spawn (defense-in-depth
against an unverified or swapped manifest reaching the gate), use the single
fail-safe call instead — it verifies *then* attests:

```ts
import { attestSpawnVerified, type SignedManifest } from "mcp-server-attestation";
attestSpawnVerified(signed as SignedManifest, { command, args });
```

## Tools (reference server `mcp-attest-demo`)

| # | Name | readOnlyHint | destructiveHint |
| - | ---- | ------------ | --------------- |
| 1 | `attest_verify_manifest` | true | false |
| 2 | `attest_inspect_spawn` | true | false |
| 3 | `attest_generate_manifest_template` | true | false |
| 4 | `attest_sign_manifest` | false | false |
| 5 | `attest_keygen` | false | false |

Annotations are honest: `attest_sign_manifest` and `attest_keygen` write files on disk so they are not read-only, but they do not destroy existing data so destructiveHint stays false. See `docs/THREAT-MODEL.md` for the per-tool capability table.

## CLI

```bash
mcp-attest keygen --out-dir ./keys --name prod
mcp-attest sign --manifest manifest.json --private-key keys/prod.key --out signed.json
mcp-attest verify --signed signed.json --pin                  # TOFU pin
mcp-attest verify --signed signed.json --sigstore             # opt-in Rekor cross-ref
mcp-attest inspect --signed signed.json --command /usr/bin/echo --arg "hello"
mcp-attest fingerprint --public-key keys/prod.pub
mcp-attest check-pin --server my-server --signed signed.json
```

`verify` exits with code 2 on bad signature, code 3 on pin mismatch.

## MCP spec compatibility

| Spec version | Status |
| --- | --- |
| 2024-11-05 | parseable in manifest, not target of reference server |
| 2025-03-26 | parseable in manifest, not target of reference server |
| 2025-06-18 | full target |

The library is transport-agnostic. The reference server is stdio-only.

## Security model

- **Trust-on-First-Use** is the default. The first time you verify a server, its public key is pinned to `~/.mcp-attest/trust.json` (override: `MCP_ATTEST_TRUST_FILE`). Subsequent verifications reject any new key for the same server name with `TRUST_PIN_MISMATCH`. This catches the Cursor-style malicious-update vector.
- **No bundled trusted-keys list.** This package does not act as a gatekeeper. If you want stronger assurance, opt into `--sigstore` to cross-reference the public-key fingerprint against the Sigstore Rekor transparency log.
- **Default-deny argument sanitizer.** `shellSafeString` blocks every ASCII shell metacharacter, NUL, CR, LF, VT, FF, NEL, zero-width characters, BOM, RTL/LTR overrides, Trojan-Source isolates, and fullwidth-Latin confusables. Allowlist behaviour requires the explicit `regex` / `enum` / `prefix` / `literal` rule kinds.
- **ReDoS-safe `regex` rules.** A `regex` rule's pattern is signed by the author, but the argument value is attacker-controlled. The sanitizer statically detects backtracking-prone patterns (nested unbounded quantifiers like `(a+)+`) and refuses to run them, so a single crafted argument cannot freeze the spawn hot path. `regex` rules also carry a `maxLength` input cap (default 4096).
- **Traversal-safe `prefix` rules.** `prefix` rules reject `..` path components by default (`denyTraversal: true`, including the `%2e%2e` encoded form), so `/safe/../../etc/passwd` is blocked even though it satisfies `prefix: "/safe/"`.
- **Verify-then-attest.** `attestSpawnVerified` checks the manifest signature before attesting the spawn in one fail-safe call — use it instead of `attestSpawnStrict` unless you have measured the per-spawn Ed25519 verify out of a genuinely hot loop.
- **Canonical JSON** is the signed surface. Re-serialisation cannot change the signed bytes.

What this package does NOT do (out of scope):
- Sandbox or containerise the server process.
- OAuth flow hardening (separate `mcp-oauth-shield` build).
- Network egress control.
- Auto-patch existing servers.

## Tests

```bash
npm install
npm run typecheck
npm test
```

Test corpus includes CVE-replay fixtures (`packages/lib/tests/fixtures/cve-2025-69256-payloads.json`, `cve-2025-61591-payloads.json`). The build is a regression check: every payload must be blocked.

## Distribution

- npm publish via GitHub Actions OIDC with `--provenance`.
- Reference server submitted to mcp.so and FastMCP Directory.
- Library separately published as `mcp-server-attestation`.

## About StudioMeyer

[StudioMeyer](https://studiomeyer.io) is an AI and design studio based in Palma de Mallorca, working with clients worldwide. We build custom websites and AI infrastructure for small and medium businesses. Production stack on Claude Agent SDK, MCP and n8n, with Sentry, Langfuse and LangGraph for observability and an in-house guard layer.

## License

MIT, Copyright 2026 Matthias Meyer (StudioMeyer). See `LICENSE`.