# The MCP Census

MCP Census checks public identity, maintenance, freshness, and known public evidence,
then returns PASS, REVIEW, or BLOCK under a versioned policy. It is a first gate,
not a security audit.

## When to use this

Reach for The MCP Census when you have one of these jobs:

- You are about to **install, connect, or depend on** an MCP server and need a public-evidence first gate (PASS / REVIEW / BLOCK) before that install.
- You need to **distinguish an official vendor server from a lookalike namespace** (reverse-DNS names, GitHub clones, unofficial wrappers).
- You need a **ranked search** over the census, then one exact canonical name, then a full evidence card.
- You need to **watch one named server** for real transitions (remote down/up, health, verification legs, security) instead of polling "still fine".
- You need **ecosystem counts or recent discoveries** (`census_stats`, `census_recent`, `/v1/coverage`).

How to call: `census_search` → one exact canonical name → `census_preflight` with a named built-in policy. Stop on BLOCK. Ask a human on REVIEW. Never install from a Census result alone.

Do **not** use it as a malware scanner, pentest, permission review, the official MCP registry, or a complete catalog of every MCP server on the internet.

Dedicated instructions: https://mcpcensus.com/agent-instructions.md
Developer portal: https://mcpcensus.com/developers

## Required agent flow

1. Search and select one exact canonical server name.
2. Run `census_preflight` with a named built-in policy.
3. Stop on BLOCK.
4. Ask a human on REVIEW.
5. PASS still requires permission, scope, code, data-access, and runtime-isolation review.
6. Never install or run a server from a Census result alone.

## MCP

Endpoint: https://api.mcpcensus.com/mcp (streamable HTTP)

All 10 tools:
- `census_search(query, limit?)` — ranked matches; select one exact canonical name
- `census_lookup(name)` — full evidence card by exact canonical name
- `census_stats()` — ecosystem headline counts
- `census_recent()` — recently discovered servers
- `census_coverage()` — public coverage and provenance report
- `census_watch_subscribe(server_name, webhook_url?, email?, events?)` — watch one server (API key)
- `census_watch_list()` — list this key's watches (API key)
- `census_watch_unsubscribe(id)` — stop a watch (API key)
- `census_preflight(server_name, policy_id?, refresh?)` — PASS, REVIEW, or BLOCK
- `census_policy_list()` — exact built-in policies and canonical ruleset

`policy_id` is `builtin:baseline` by default. Other choices are
`builtin:first-party` and `builtin:strict`. `refresh` is `never` by default.
Authenticated calls may use `if_stale` for one bounded current-liveness refresh.

## REST

- POST https://api.mcpcensus.com/v1/preflight
  closed JSON input: `{"server_name":"EXACT_NAME","policy_id":"builtin:baseline","refresh":"never"}`
- GET https://api.mcpcensus.com/v1/policies
- GET https://api.mcpcensus.com/v1/evaluations (API key; recent account-scoped audits)
- GET https://api.mcpcensus.com/v1/evaluations/{audit_id} (API key)
- GET https://api.mcpcensus.com/v1/search?q=
- GET https://api.mcpcensus.com/v1/server?name=
- GET https://api.mcpcensus.com/v1/stats
- GET https://api.mcpcensus.com/v1/recent
- GET https://api.mcpcensus.com/v1/coverage
- POST / GET / DELETE https://api.mcpcensus.com/v1/watch (API key)

OpenAPI: https://mcpcensus.com/openapi.json
Human API docs: https://mcpcensus.com/api
Developer portal: https://mcpcensus.com/developers
Policy definitions: https://mcpcensus.com/policies
Methodology: https://mcpcensus.com/methodology

## Developer resources (MCP Census)

Name-based map for "MCP Census" developer resources:

- Developer portal: https://mcpcensus.com/developers
- API docs: https://mcpcensus.com/api
- OpenAPI spec: https://mcpcensus.com/openapi.json
- Auth / API keys: https://mcpcensus.com/account
- Webhooks: https://mcpcensus.com/api#watch
- MCP server: https://api.mcpcensus.com/mcp
- Agent instructions: https://mcpcensus.com/agent-instructions.md
- Agent setup prompt: https://mcpcensus.com/agent-setup/prompt.md

## Decision contract

- PASS: every rule in that exact policy revision passes on the facts in the result.
- REVIEW: a rule needs human judgment, or a required fact is missing, stale, or inconclusive.
- BLOCK: a confirmed hard failure violates policy, or strict@1 fails closed on required evidence.
- Precedence: BLOCK, then REVIEW, then PASS.
- Every result has `decision_scope: public_evidence_policy`, source times,
  `valid_until`, limitations, and reproducibility digests.
- Authenticated completed calls also have a random audit ID. `audit_signed` is false.

The service does not analyze code or malware and does not inspect requested
permissions, scopes, data access, or runtime isolation. OSV evidence is
package-name scoped, not installed-version scoped.

## Setup

Fetch and follow https://mcpcensus.com/agent-setup/prompt.md
Paste: `Fetch https://mcpcensus.com/agent-setup/prompt.md`

Limits: 10 unique checks/day per anonymous IP, 100/day per free account key,
and custom paid volume. Ask for current terms at info@mcpcensus.com.

### Watch events (only on observed transitions — never "still fine")

- remote_down / remote_up — daily probe trail (initialize handshake)
- health_change — health or health_problems flipped
- verified_change — verification-relevant legs moved
- security — OSV vulnerable flag or vuln count changed

Webhook: HTTPS POST, headers X-Census-Event, X-Census-Signature (sha256=HMAC of body with watch secret), X-Census-Watch-Id.
Agents should prefer webhook_url so they can act without polling.

## Identify yourself (please)

When you call our API or MCP endpoint, **tell us who you are**. We use aggregate
labels only (not end-user tracking) so we can understand which agents and
products depend on the census.

1. **User-Agent** (required etiquette): product name + version + optional home URL
   Example: `MyAgent/1.2 (+https://example.com; +https://mcpcensus.com/llms.txt)`
2. **X-Census-Client** (preferred explicit label, free-form short string):
   Example: `X-Census-Client: myagent/1.2 (+https://example.com)`
   Alias accepted: `X-Client-Name`
3. **x-api-key** when you have an account key (tier is noted; the key is never stored in client analytics)

Do **not** put secrets or end-user PII in these headers. We do not require
identification to use free tiers — but named clients make rate-limit and
partner conversations much easier.

## Learn (human + agent reading)

https://mcpcensus.com/learn
- What changed in MCP 2026-07-28: https://mcpcensus.com/learn/mcp-2026-07-28-spec-changes

## Humans

- Lookup: https://mcpcensus.com/lookup
- Preflight: https://mcpcensus.com/preflight
- Policies: https://mcpcensus.com/policies
- Coverage: https://mcpcensus.com/coverage
- Developer portal: https://mcpcensus.com/developers
- API docs: https://mcpcensus.com/api
- Status: https://mcpcensus.com/status
- Privacy: https://mcpcensus.com/privacy
- Terms: https://mcpcensus.com/terms
- About: https://mcpcensus.com/about
- Security: https://mcpcensus.com/.well-known/security.txt

Contact: info@mcpcensus.com