<!-- Generated from https://zscreen.zeruai.org/docs/mcp by scripts/agent-docs.mjs. Do not edit. -->

# MCP server

zScreen is available as a hosted Model Context Protocol server, so an assistant can screen a wallet through a tool call instead of an HTTP request. There is nothing to install and nothing to run.

## Connect

The bearer token is an ordinary zScreen API key, the same one the HTTP API takes. Sign in at [/signin](https://zscreen.zeruai.org/signin) with Google or a wallet, then create a key from [/dashboard](https://zscreen.zeruai.org/dashboard). It is shown once, on that screen, so copy it before navigating away. Paste it in place of `zsk_...` below.

In Claude Code:

```
claude mcp add --transport http zscreen \
  https://zscreenapi.zeruai.org/mcp \
  --header "Authorization: Bearer zsk_..."
```

Clients that take a configuration file, such as Cursor and VS Code, want the same three things: the transport, the URL, and the header.

```
{
  "mcpServers": {
    "zscreen": {
      "type": "http",
      "url": "https://zscreenapi.zeruai.org/mcp",
      "headers": { "Authorization": "Bearer zsk_..." }
    }
  }
}
```

Clients that only offer OAuth fields, which includes the Claude web connector, cannot use a key header yet. Use Claude Code, Cursor or VS Code until that lands.

## Tools

- `screen_wallet(address)` screens one address and returns the verdict.
- `get_job(job_id)` polls a wallet that had to be fetched.
- `get_screening(screening_id)` returns one record from your account.
- `list_wallet_screenings(address)` lists your screenings for an address.

## Read assessed first

Every result carries an `assessed` field, and it is the one to branch on. Only a result with `assessed: true` carries a verdict.

```
{
  "ok": true,
  "assessed": true,
  "verdict": "FLAGGED",
  "risk_score": 100,
  "decided_by": {
    "rule": "ofac_contact",
    "source": "rule",
    "reason": "This wallet dealt directly with an address on the OFAC sanctions list."
  }
}
```

A wallet nobody has looked at yet comes back with `assessed: false` and a null verdict. It is not a clean wallet. The same is true when the free tier is spent and when the chain has nothing to score.

```
{
  "ok": true,
  "assessed": false,
  "status": "queued",
  "job_id": 41,
  "verdict": null,
  "note": "This wallet has no history on file and is being fetched. Poll get_job with job_id. A wallet is NOT low risk because it has not been assessed yet."
}
```

Rate limits and brief outages also return `assessed: false`, with a `retry_after`, so a failure to answer is never mistaken for an answer.

## Limits

Tool calls are screens. They count against the same free tier and the same requests-per-second limit as the API, on the key you configured, so [Rate limits and the free tier](https://zscreen.zeruai.org/docs/limits) applies unchanged.

When the key's free tier is spent, `screen_wallet` returns `assessed: false` with `status: "payment_required"` and a `payment` object. The agent cannot pay from inside MCP: a person, or an x402 client, pays $0.50 per screen over the HTTP API.

## No MCP in your client?

An agent can call the HTTP API directly instead. [skill.md](https://zscreen.zeruai.org/skill.md) is a single file that tells it how, and [For agents](https://zscreen.zeruai.org/docs/agents) covers the rest of what this site offers machines.