The MCP Census

Get the live health verdict for one MCP server by its exact registry name (e.g. 'io.github.owner/name'). Returns stars, last-push recency, gone/archived/deprecated flags, name-collision count, and a fact-based health verdict (healthy | issues | unknown).

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Exact MCP registry server name"
    }
  },
  "required": [
    "name"
  ]
}

Search MCP servers by keyword or partial name (e.g. 'github', 'postgres'). Returns ranked matches with health/trust. Also returns: resolved_query (auto typo fix), disambiguate (when unsure), known_brand (we recognize a strong product but it has no official MCP — e.g. CodeRabbit), research (watchlist/confirmed_absent), query_intent (brand_lookup|category|package|install_gate|junk — does not change ranking), intent_cta (preflight when they asked an install-gate question). Prefer official_match=true rows. Never invent servers.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Keyword or partial server name (>= 2 chars). Typos and space variants are resolved when confident."
    },
    "limit": {
      "type": "number",
      "description": "Max results 1–50 (default 20)"
    }
  },
  "required": [
    "query"
  ]
}

Ecosystem headline numbers from the live census (same payload as GET /v1/stats). Unmetered. Returns total servers, healthy/issues counts, popular (gh_stars>=1000), remote-capable count, github-linked count, and captured_at. No invented metrics.

{
  "type": "object",
  "properties": {}
}

Newest MCP servers by real first_seen_at (same payload as GET /v1/recent). Unmetered. Only rows with a known first-seen date — never invents or guesses discovery times. Optional limit 1–50 (default 20).

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max results 1–50 (default 20)"
    }
  }
}

Public transparency report (same payload as GET /v1/coverage). Unmetered. Live D1 census/identity/remote/protocol/adoption/pipeline counts plus method notes — never invents completeness percentages or a brand_audit punch list.

{
  "type": "object",
  "properties": {}
}

Subscribe this agent (or a human email) to alerts for ONE specific MCP server. Fires only on real observed changes: remote_down, remote_up, health_change, verified_change, security. Requires x-api-key. Prefer webhook_url (https) so your agent can receive POST callbacks; email optional. Returns a watch id + HMAC secret (X-Census-Signature: sha256=…). Free tier: 5 watches; pro: 50.

{
  "type": "object",
  "properties": {
    "server_name": {
      "type": "string",
      "description": "Exact registry name to watch"
    },
    "webhook_url": {
      "type": "string",
      "description": "https URL that will receive signed POST event payloads"
    },
    "email": {
      "type": "string",
      "description": "Optional human email for the same alerts"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Subset of remote_down,remote_up,health_change,verified_change,security,tools_changed (default: all)"
    },
    "label": {
      "type": "string",
      "description": "Optional agent-chosen label"
    }
  },
  "required": [
    "server_name"
  ]
}

List active per-server watches for this API key. Requires x-api-key.

{
  "type": "object",
  "properties": {}
}

Deactivate a watch by id. Requires x-api-key that owns the watch.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Watch id from census_watch_subscribe"
    }
  },
  "required": [
    "id"
  ]
}

Evaluate one exact MCP server under a documented built-in install policy. Returns PASS, REVIEW, or BLOCK with evidence reasons, freshness, digests, and explicit limits. This is a first gate, not a security audit. refresh=if_stale requires x-api-key.

{
  "type": "object",
  "properties": {
    "server_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Exact canonical Census server name"
    },
    "policy_id": {
      "type": "string",
      "enum": [
        "builtin:baseline",
        "builtin:first-party",
        "builtin:strict"
      ],
      "default": "builtin:baseline"
    },
    "refresh": {
      "type": "string",
      "enum": [
        "never",
        "if_stale"
      ],
      "default": "never"
    }
  },
  "required": [
    "server_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "decision": {
      "type": "string",
      "enum": [
        "PASS",
        "REVIEW",
        "BLOCK"
      ]
    },
    "decision_scope": {
      "const": "public_evidence_policy"
    },
    "meaning": {
      "type": "string"
    },
    "server_name": {
      "type": "string"
    },
    "policy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string"
        },
        "revision": {
          "type": "integer",
          "minimum": 1
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:"
        }
      },
      "required": [
        "id",
        "revision",
        "digest"
      ]
    },
    "reasons": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "result": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "code",
          "result",
          "summary",
          "evidence"
        ]
      }
    },
    "facts": {
      "type": "object"
    },
    "facts_digest": {
      "type": "string",
      "pattern": "^sha256:"
    },
    "decision_input_digest": {
      "type": "string",
      "pattern": "^sha256:"
    },
    "engine_version": {
      "type": "string"
    },
    "evaluated_at": {
      "type": "string",
      "format": "date-time"
    },
    "valid_until": {
      "type": "string",
      "format": "date-time"
    },
    "audit_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "audit_signed": {
      "const": false
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ok",
    "decision",
    "decision_scope",
    "meaning",
    "server_name",
    "policy",
    "reasons",
    "facts",
    "facts_digest",
    "decision_input_digest",
    "engine_version",
    "evaluated_at",
    "valid_until",
    "audit_id",
    "audit_signed",
    "limitations"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

List the exact immutable Preflight v1 built-in policy objects, canonical ruleset, and policy digests. Unmetered.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "policies": {
      "type": "array",
      "minItems": 3,
      "maxItems": 3,
      "items": {
        "type": "object"
      }
    },
    "ruleset": {
      "type": "object"
    },
    "policy_digests": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "pattern": "^sha256:"
      }
    },
    "audit_signed": {
      "const": false
    }
  },
  "required": [
    "ok",
    "policies",
    "ruleset",
    "policy_digests",
    "audit_signed"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Show remaining Census credits for this API key (wallet after the UTC-month grant). Unmetered. Without a key, returns anonymous unique-per-day remaining — not a wallet.

{
  "type": "object",
  "properties": {}
}

Census stamp for one exact MCP server under a built-in policy. Same input as census_preflight. Returns the preflight body plus compact CENSUS-STAMP/1 text and stamp_json. Cost matches preflight. Never connect without a stamp. PASS is not a malware scan or permission review.

{
  "type": "object",
  "properties": {
    "server_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Exact canonical Census server name"
    },
    "policy_id": {
      "type": "string",
      "enum": [
        "builtin:baseline",
        "builtin:first-party",
        "builtin:strict"
      ],
      "default": "builtin:baseline"
    },
    "refresh": {
      "type": "string",
      "enum": [
        "never",
        "if_stale"
      ],
      "default": "never"
    }
  },
  "required": [
    "server_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Contested identity for one exact server_name: official_for, name_collision_count, and up to 10 other census server_name values sharing the same namespace brand or tail. Never invents lookalikes. Cost 1.

{
  "type": "object",
  "properties": {
    "server_name": {
      "type": "string",
      "description": "Exact canonical Census server name"
    }
  },
  "required": [
    "server_name"
  ]
}

Audit a whole MCP client config in one call (.mcp.json, claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json, Codex config.toml text). Resolves every entry without guessing (url → remote_url, npx → npm package, uvx → PyPI package) and returns one PASS / REVIEW / BLOCK / UNKNOWN verdict per entry under a built-in policy, plus CENSUS-AUDIT/1 text, valid_until_epoch and exit_code (1 on any BLOCK). UNKNOWN is never upgraded to PASS. Cost 1 credit per config per UTC day; keyless callers get one config of ≤25 entries per IP per day. Not a malware scan; PASS is not a sandbox. Strip env/headers before sending.

{
  "type": "object",
  "properties": {
    "config": {
      "description": "The config document: an object with mcpServers | servers | mcp_servers, a list under entries[], or raw text (JSON or Codex config.toml)",
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "array"
        }
      ]
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "toml"
      ]
    },
    "policy_id": {
      "type": "string",
      "enum": [
        "builtin:baseline",
        "builtin:first-party",
        "builtin:strict"
      ],
      "default": "builtin:baseline"
    },
    "previous_tools_digests": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "alias → tools_digest from your last audit; sets tools_drift per entry"
    },
    "strict": {
      "type": "boolean",
      "default": false,
      "description": "exit_code 2 when any entry is REVIEW or UNKNOWN"
    }
  },
  "required": [
    "config"
  ],
  "additionalProperties": false
}

The Census change feed (CENSUS-CHANGES/1): observed transitions across every server — server_new, remote_down, remote_up, tools_changed, health_change, verified_change, security, endpoint_moved, registry_status, spec_era_change. Cursor-paginated: pass next_cursor back as since. Filter by events, server_names or namespace_domain. Only real transitions, never 'still fine'. Unmetered in v1; poll hourly. Not a malware scan.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "next_cursor from the previous page, or an RFC 3339 time for the first call"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Event names to include (default all)"
    },
    "server_names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exact canonical names to include (≤50)"
    },
    "namespace_domain": {
      "type": "string",
      "description": "Registrable domain of a DNS-verified namespace, e.g. notion.com"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 100
    }
  },
  "additionalProperties": false
}