attester-mcp

# attester-mcp

MCP server for [attester.dev](https://attester.dev): verification and
API-existence oracle tools for AI agents, callable from any MCP client
(Claude Code, Cursor, Windsurf, LangChain, CrewAI).

Every result ships with a wallet-signed attestation you can verify without
trusting us: `POST https://attester.dev/receipts/verify` is free.

## Quickstart: free oracle tools, no keys

```bash
uvx attester-mcp
```

That is the whole install. Four oracle tools work immediately: no account,
no API key, no wallet. You get 25 free calls per day per client IP, shared
across the four tools, resetting 00:00 UTC.

| Tool | What it does | Price per call |
|---|---|---|
| `attester_package_exists` | Does this PyPI/npm package name really exist? Typosquat-adjacency flags on misses. | Free (25/day keyless); $0.002 paid |
| `attester_symbol_exists` | Does this function, class, or constant exist in the package? Closest-match suggestions on misses. | Free (25/day keyless); $0.005 paid |
| `attester_symbol_signature` | Exact signature, structured params, docstring, deprecation status, resolved at a pinned version. | Free (25/day keyless); $0.01 paid |
| `attester_version_diff` | Symbol-level diff between two pinned versions: added, removed, changed, breaking/additive/neutral. | Free (25/day keyless); $0.02 paid |

**Claude Code / Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "attester": {
      "command": "uvx",
      "args": ["attester-mcp"]
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`): same shape as above.

### Steer your agent: CLAUDE.md / Cursor Rules snippet

```
- Before installing or importing a package, call attester_package_exists (and attester_symbol_exists for specific functions) to confirm the name exists. Never import a name the oracle says does not exist.
```

## Paid tools

| Tool | What it does | Price per call |
|---|---|---|
| `oracle_verify_work` | Check another agent's work: citation support, code correctness, data/schema validation. Verdict plus signed attestation. | $0.15 USDC |
| `oracle_code_research` | Cited coding research; citations are re-checked and the proof attached. | $0.10 USDC |
| `oracle_judge` | Grade an output against your rubric; signed score with per-criterion evidence. | $0.10 USDC |
| `oracle_watchtower_report` | Signed 24h report on whether an x402 service honors its advertised prices. | $0.05 USDC |
| `oracle_spend_check` | Pre-payment counterparty check: should your agent pay this address? | $0.005 USDC |

Payment works two ways:

- **Prepaid credits (humans, no crypto):** buy a $5 pack at
  [this Stripe link](https://buy.stripe.com/bJefZhfGo9Uy6zF9ckaZi00), claim
  the `att_live_...` key once at
  `https://attester.dev/credits/claim?session_id=cs_...`, and set
  `ATTESTER_API_KEY=att_live_...` in the server env. Every paid call
  deducts from the balance. Check it at
  `GET https://attester.dev/credits/balance` with the key.
  (`CREDITS_API_KEY` still works as an alias.) The free oracle tools honor
  the key too: the demo routes skip the daily quota for it and never
  charge.
- **x402 (agents with wallets):** set `BUYER_PRIVATE_KEY` to a Base wallet
  with USDC. The wrapper pays per call automatically (402, sign, retry)
  and sends the wallet address as `X-Payer`, which keys the paid
  endpoints' free quotas.

Without any key, the paid endpoints answer HTTP 402 with payment terms in
the body.

## Agent skill bundle (`skills/attester`)

The same API, packaged as an Agent Skill so agent configs load it as a
default tool: when-to-use rules, exact curl per endpoint (the keyless
`/demo/v1/*` free path for oracle checks, `X-Payer` free quotas for the
rest), verdict reading, and receipt verification.

Install paths:

```bash
# Claude Code
/plugin marketplace add maminihds/attester-mcp

# skills.sh CLI (Claude Code, Cursor, Codex, 30+ agents)
npx skills add maminihds/attester-mcp

# OpenClaw (manifestless Claude bundle)
openclaw plugins install https://github.com/maminihds/attester-mcp
```

Or copy `skills/attester/` into `~/.claude/skills/` manually. The bundle
has a helper (`skills/attester/scripts/call.py`, stdlib + httpx) and two
worked transcripts in `skills/attester/examples/`.

## Install from source

```bash
pip install -r requirements.txt
python server.py            # stdio (default, for agents)
python server.py --http     # streamable-http on :8100
```

Environment variables:

- `SERVER_URL`: API base URL, defaults to `https://attester.dev`.
- `ATTESTER_API_KEY`: prepaid credits key (`att_live_...`), optional.
- `BUYER_PRIVATE_KEY`: Base wallet for x402 payment, optional.

## Example clients

`examples/plain_python.py`: direct x402-paid call with the official SDK.
`examples/langchain_example.py`: LangChain tool wrapper.

## Links

- Site: https://attester.dev
- OpenAPI: https://attester.dev/openapi.json
- llms.txt: https://attester.dev/llms.txt
- Directory listing: https://x402-list.com/services/attester-verification-oracle-verified-research