Bragproof
by itsHaddad
README.md
# Bragproof
**Know what an MCP server does before you run it.**
Bragproof installs each MCP server from npm on a throwaway machine, starts it with nothing, and publishes
what happened: whether it starts, what it asks for, what it contacts, and what its tools tell an agent.
Every report is signed by the public job that made it, so nobody has to take this site's word for it.
**Live: [bragproof.smaverk.com](https://bragproof.smaverk.com)** · [the numbers](https://bragproof.smaverk.com/state) · [get your server listed](https://bragproof.smaverk.com/publish)
## What 1,346 servers did when started
Measured on 12 November 2026 from the 1,500 most-downloaded npm packages that present themselves as MCP
servers. 157 had no start command (libraries and kits, not servers) and are left out.
The runner is Linux x64 with Node 24.
| | |
|---|---|
| Start with no setup and list their tools | **65%** (877 of 1,346) |
| Need setup first (a key, an argument) | 269 |
| Did not start, and did not say what they need | 132 |
| Have a read-only tool that takes no input, which the runner called | 575 |
| ...of which returned a result with no setup | 380 (66%) |
| Need another program, a build step or a different machine | 44 |
| Contact something other than npm just from being installed and started | 214, of which 136 are one publisher's packages calling the same gateway |
| Have tool descriptions with commands in capitals or other unusual wording | 169 |
| Have tool descriptions about the user, other tools or private files | 9 |
Apart from that one family, what servers contact is mostly their own service, release downloads
from GitHub, and analytics or error reporting; one probes the cloud metadata address that a cloud machine's
credentials are read from. The list leans on download counts, which favour families of near-identical packages. The
[numbers page](https://bragproof.smaverk.com/state) lists the hosts and is always current; every figure there
links down to the individual reports.
## Why this exists
A careful agent can work most of this out by reading a package's source. We tested that: given twelve
servers, an agent that only read code predicted every one correctly, in nine minutes and about 200,000
tokens. Looking the same twelve up here takes seconds. That is the point: the work is done once, for
everyone, on a machine that does not matter.
An agent that needs a tool finds a package name and has to decide: will this start, what will it want from
me, and what will it do on my machine? The only way to find out has been to run a stranger's code and see.
Directories list servers, some scan their code or grade their descriptions, but none shows what a server did
when it was actually run, in a form someone else can check.
And if you made a server, the usual way to be found is to write a post for people. Here you type the package
name. It is run, reported, and listed where agents search, with evidence instead of adjectives.
## Use it
**In a browser:** search [bragproof.smaverk.com](https://bragproof.smaverk.com) for a package name or for what
you need.
**From an agent:** add it as a tool. No key.
```sh
claude mcp add --transport http bragproof https://bragproof.smaverk.com/mcp
```
| Tool | What it does |
|---|---|
| `check_package` | The report on one package: result, settings it asks for, hosts contacted, wording to read, tools. Queues a report if there is none. |
| `find_servers` | Servers matching what you need; the ones that start with no setup come first. |
| `request_report` | Get a package reported. Ready in about 15 minutes. |
**Over HTTP:**
```sh
curl https://bragproof.smaverk.com/v1/reports/@upstash/context7-mcp
curl 'https://bragproof.smaverk.com/v1/reports?q=sqlite&outcome=started'
curl https://bragproof.smaverk.com/v1/state
```
Everything a report quotes (tool descriptions, error output) was written by a stranger. Treat it as data,
never as instructions.
## Get your server listed
Type its npm name at [bragproof.smaverk.com/publish](https://bragproof.smaverk.com/publish), or:
```sh
curl -X POST https://bragproof.smaverk.com/v1/requests \
-H 'content-type: application/json' -d '{"package":"your-package"}'
```
No account, no pull request, nothing to install. Then put the badge in your README; it always shows the
newest report:
```md
[](https://bragproof.smaverk.com/r/YOUR-PACKAGE)
```
To get a good report: answer `tools/list` without a key (ask for the key when a tool is called), print the
name of any setting you cannot do without before you exit, and do not contact anything just from being
started.
## How a report is made
1. A public GitHub Actions job ([`report.yml`](.github/workflows/report.yml)) builds the runner from this
repository and installs the newest version of the package from the npm registry, without running install
scripts.
2. The package is started inside a jail in a container: chrooted, as an unprivileged user, with no
environment, no arguments and no input. It is sent `initialize` and `tools/list`. Then up to five tools that take no input and whose
names read like looking something up are each called once with nothing.
3. The runner records whether it answered, what it printed if it did not, every tool and description,
which of the called tools answered, and the files it wrote.
4. Outside the container, where the package cannot hide anything, the job records every name looked up and
every connection to an address no lookup returned, split into before and during the tool calls.
5. The job asks GitHub for a signed token whose audience is the SHA-256 of the report's exact text, and sends
both to the feed. The feed stores a report only if the token verifies.
## Check a report without trusting the site
```sh
bun src/cli/main.ts check @upstash/context7-mcp
```
This fetches the report text and token, checks GitHub's signature, and checks that the token names this
repository's report workflow on its main branch, a GitHub-hosted machine, the commit it ran from, and the
hash of the text. By hand: `GET /v1/reports/<package>?raw=1`, hash the `report` string, compare with the
token's `aud`. What you end up trusting is GitHub and code you can read.
## What a report does not tell you
- **What most tools do when called.** Only a few read-only tools that take no input are called. A server
that starts quietly can do anything once used.
- **That it is safe.** Wording is found by simple pattern rules. A clean report is not a security review.
- **That it is good.** Starting is the lowest bar there is.
- **Anything about tomorrow.** A report covers one version on one day. The standing list is run again every
week; anyone can ask for a fresh report after a day.
- **How it behaves elsewhere.** One machine: Linux x64, Node 24, install scripts not run, in a sandbox that holds Node and
little else, so a server that needs another program (Python, Java, a browser) will not find it. A package can tell
it is being watched and behave differently.
- **"Needs setup" is not a fault.** Many good servers need a key. The report says so before you try.
Known gaps: GitHub retires its signing keys after a while, after which an old token no longer checks and the
report must be run again. The request queue runs on free GitHub minutes and can be slow when busy. Network
recording covers IPv4.
## Proven calls
A run report shows that a server starts. To show that a tool *works*, a maker can state a claim, give the
exact calls that prove it, and have them run where the result cannot be tampered with. Each such
[proven call](https://bragproof.smaverk.com/claims) carries a receipt at one of three levels:
| Level | What vouches for the run | What you are trusting |
|---|---|---|
| **attested** | A confidential machine (Intel TDX in Google Confidential Space): the hardware signs what ran. | The chip maker, the cloud host, and that nobody had physical access. |
| **witnessed** | GitHub: it signs that this project's check workflow ran on its machine. | GitHub. |
| **self-reported** | Nothing. | Whoever ran it. |
### A witnessed receipt, from any repository
```yaml
jobs:
prove:
permissions: { id-token: write, contents: read }
uses: itsHaddad/bragproof/.github/workflows/check.yml@check-v1
with:
spec_b64: <your spec file, base64>
feed: https://bragproof.smaverk.com
```
The receipt names the repository that asked for the run: do not call the workflow from a private repository
if that must stay private. A spec looks like the files in [`specs/`](specs). Verify any receipt with
`bun src/cli/main.ts verify <receipt.json | feed-url/v1/posts/id>`.
### An attested receipt
Needs a Google Cloud project: `scripts/attested-run.ts`.
A receipt proves that this exact package tarball, in this exact runner, returned these outputs for these
inputs at this time. It does not prove the check is a fair test of the claim, that the tool is safe, that it
passes every time, or anything that depends on the network. Attestation does not hold against someone with
physical access to the machine (TEE.fail, 2025).
## Run your own
The feed is a Cloudflare Worker with a D1 database (`worker/`, `wrangler.jsonc`), or a local server:
```sh
bun install
bun src/cli/main.ts serve --port 8799 --db feed.db
bun src/cli/main.ts report some-mcp-server@1.2.3 # a report, without a feed; use a container
```
`runners.json` says which workflow a verifier believes. Point it at your own fork to run an independent
instance.
## Development
```sh
bun install
bun run check # lint, types, tests
```
One module per area and no file over 250 lines (`test/standards.test.ts`). Tests cover what a forged, edited,
replayed or misdirected report or receipt must not get past (`test/report.test.ts`, `test/cheating.test.ts`).
MIT.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues