MCP Census developer API

# search
curl "https://api.mcpcensus.com/v1/search?q=github" \
  -H "x-api-key: YOUR_KEY"

# one server
curl "https://api.mcpcensus.com/v1/server?name=io.github.netdata/mcp-server" \
  -H "x-api-key: YOUR_KEY"

Headers: x-ratelimit-remaining, x-credits-remaining, x-tier. No key = 10 unique/day per IP. Account = credits (prices). Same query or server again that UTC day is free. Empty wallet returns 402 payment_required. &limit= default 20, max 50.

Apply one named policy to one exact server

Input is closed. policy_id defaults to builtin:baseline. refresh defaults to never. if_stale needs an account key and can only probe the canonical stored Census URL under bounded quota and cooldown rules.

# exact policies and canonical ruleset
curl https://api.mcpcensus.com/v1/policies

# evaluate one exact canonical name
curl -X POST https://api.mcpcensus.com/v1/preflight \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"server_name":"io.github.owner/name","policy_id":"builtin:baseline","refresh":"never"}'

# compact stamp (same input, 5 credits; same-day repeat free)
curl "https://api.mcpcensus.com/v1/stamp?name=io.github.owner/name&policy_id=builtin:baseline" \
  -H "x-api-key: YOUR_KEY"

# wallet
curl -H "x-api-key: YOUR_KEY" https://api.mcpcensus.com/v1/credits

# authenticated audit history
curl -H "x-api-key: YOUR_KEY" https://api.mcpcensus.com/v1/evaluations
curl -H "x-api-key: YOUR_KEY" https://api.mcpcensus.com/v1/evaluations/AUDIT_ID

Every completed result includes ordered reasons, facts, source times, facts_digest, policy.digest, decision_input_digest, evaluated_at, valid_until, audit_signed: false, and limitations. Authenticated completed calls also include a random account-scoped audit ID retained for 90 days. Digests are not signatures.

Exact policy objects → · Method and limits → · Human console →

Point a client at the streamable HTTP endpoint. Tools:

• census_search — search and select one exact canonical name (1 credit)
• census_lookup — full evidence card for an exact name (1 credit)
• census_stats — ecosystem headline counts (unmetered)
• census_recent — recently discovered servers (unmetered)
• census_coverage — public coverage and provenance report (unmetered)
• census_watch_subscribe — watch one server (API key, 10 credits)
• census_watch_list — list watches (API key)
• census_watch_unsubscribe — stop a watch (API key)
• census_preflight — PASS, REVIEW, or BLOCK for one exact name and policy (5 credits)
• census_stamp — compact CENSUS-STAMP/1 from the same input as preflight (5 credits)
• census_audit_config — one PASS/REVIEW/BLOCK/UNKNOWN line per entry of a whole MCP config (1 credit per config per UTC day; keyless allowance per IP). REST twin: POST /v1/audit; resolver only: POST /v1/resolve.
• census_changes — the change feed: observed transitions across every server (server_new, remote_down/up, tools_changed, health_change, verified_change, security, endpoint_moved, registry_status, spec_era_change), cursor-paginated. REST twin: GET /v1/changes?since= (unmetered in v1; poll hourly). Contract: /agent-setup/changes.md.
• census_credits — wallet remaining / grant / purchased (unmetered)
• census_lookalikes — exact-name collisions for one server (1 credit)
• census_policy_list — exact policies and canonical ruleset (unmetered)

Required flow: census_search then census_preflight or census_stamp before connect; stop on BLOCK; ask a human on REVIEW; PASS still needs permission and code review; never install from a Census result alone. REST: GET /v1/stamp, GET /v1/credits.

{
  "mcpServers": {
    "mcp-census": {
      "url": "https://api.mcpcensus.com/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

Best path: paste this into any coding agent and let it install itself — same pattern as Cloudflare’s agent setup.

Fetch https://mcpcensus.com/agent-setup/prompt.md

Or one-click / copy-paste for a specific client. No button pretends more than the client can do.

Endpoint: https://api.mcpcensus.com/mcp · agent install guide: /agent-setup/prompt.md · CI: census-preflight.yml · product map: /llms.txt · prices: /pricing

Subscribe to one MCP server at a time. We notify only when something real changes on that server — remote goes down or comes back, health flips, verification-relevant legs move, or OSV security findings change. No noise when nothing happened.

Agent path (preferred): HTTPS webhook. Your agent POSTs a subscribe call; we POST signed events back. Human path: email. Subscribe costs 10 credits. Existing watch caps still apply.

# subscribe (API key required)
curl -X POST https://api.mcpcensus.com/v1/watch \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"server_name":"com.vercel/vercel-mcp","webhook_url":"https://your.agent/hooks/census"}'

# list · unsubscribe
curl -H "x-api-key: YOUR_KEY" https://api.mcpcensus.com/v1/watch
curl -X DELETE -H "x-api-key: YOUR_KEY" "https://api.mcpcensus.com/v1/watch?id=WATCH_ID"

# MCP tools (same server): census_watch_subscribe · census_watch_list · census_watch_unsubscribe

Webhook headers: X-Census-Event, X-Census-Signature: sha256=… (HMAC of body with the watch secret), X-Census-Watch-Id. Events: remote_down · remote_up · health_change · verified_change · security. Full agent notes in /llms.txt.

{
  "server_name": "io.github.owner/name",
  "health": "healthy | issues | unknown",
  "health_problems": ["repo_gone", "npm_deprecated", ...],
  "verified": true,
  "gh_stars": 1234, "months_since_push": 0.9,
  "gh_archived": false, "npm_deprecated": false,
  "name_collision_count": 3, "registry_status": "active",
  "trust_score": 78,
  "trust_factors": [{ "factor": "repo_live", "points": 10, "pillar": "maintenance",
      "evidence": "GitHub repo confirmed present and not archived" },
    { "factor": "awesome_listed", "points": 2, "pillar": "adoption",
      "evidence": "repository is listed in awesome-mcp-servers — https://github.com/punkpeye/awesome-mcp-servers" }, ...],
  "trust_pillars": [{ "pillar": "identity", "points": 15, "max": 20 },
      { "pillar": "maintenance", "points": 41, "max": 59 },
      { "pillar": "adoption", "points": 24, "max": 51 },
      { "pillar": "security", "points": 0, "max": 0 }], ...
}

health is healthy / issues / unknown. trust_score is 0–100 with trust_factors (and pillar groups) in the same response. Unknown is not a guess. Registry, GitHub, npm, PyPI.

verified: true = live repo (not archived) + live package + active registry listing. Not a claim that npm publisher equals GitHub owner.

Free SVG badge for READMEs. No key. Links to lookup.

# the image
GET https://mcpcensus.com/badge/io.github.owner/name.svg

# markdown embed
[![MCP Census](https://mcpcensus.com/badge/io.github.owner/name.svg)](https://mcpcensus.com/lookup?q=io.github.owner/name)