---
title: "Audit a whole MCP client config: one PASS / REVIEW / BLOCK / UNKNOWN per entry"
method: POST
path: "/v1/audit"
---

# Audit a whole MCP client config: one PASS / REVIEW / BLOCK / UNKNOWN per entry

`POST /v1/audit`

## Request

- Base URL: `https://api.mcpcensus.com`
- URL: `https://api.mcpcensus.com/v1/audit`
- Auth: one of:
  - none
  - API key in header `x-api-key`

Resolves every entry of a config document without guessing (url → remote_url, npx → npm package, uvx → PyPI package, canonical alias → server_name) and evaluates each resolved server under one built-in policy through the same core as /v1/preflight. Returns CENSUS-AUDIT/1 JSON and text, valid_until_epoch for shell caches and an exit code for CI. UNKNOWN is a real verdict and is never upgraded to PASS. Keyed: 1 credit per config digest per UTC day. Keyless: one config of ≤25 entries per IP per UTC day, repeats free. Not a malware scan; PASS is not a sandbox. Contract: https://mcpcensus.com/agent-setup/audit.md

## Request body

- AuditInput: A config document (mcpServers | servers | mcp_servers), an envelope {config, format, policy_id, previous_tools_digests, strict}, a plain {entries:[...]} list, or raw Codex config.toml text sent as text/plain. Only url, command, args and type are read; strip env and headers before posting.
  - `config` union: Config document (object) or raw text (JSON or Codex TOML)
    - object
    - string
  - `format` 'json' | 'toml'
  - `policy_id` 'builtin:baseline' | 'builtin:first-party' | 'builtin:strict'
  - `previous_tools_digests` object: alias → tools_digest from your last audit; sets tools_drift per entry
  - `strict` boolean: exit_code 2 when any entry is REVIEW or UNKNOWN
  - `mcpServers` object
  - `servers` object
  - `mcp_servers` object
  - `entries` object[]
    - `name` string
    - `url` string
    - `command` string
    - `args` string[]

## Response `200`

Completed audit

- AuditResult
  - `ok` unknown
  - `spec` 'CENSUS-AUDIT/1'
  - `policy` object
    - `id` string
    - `digest` string, nullable
  - `as_of` string, date-time
  - `valid_until` string, date-time, nullable: Minimum over resolved entries
  - `valid_until_epoch` integer, nullable
  - `config_digest` string
  - `config_format` string
  - `decision_scope` 'public_evidence_policy'
  - `summary` object
    - `entries` integer
    - `pass` integer
    - `review` integer
    - `block` integer
    - `unknown` integer
  - `exit_code` 0 | 1 | 2: 1 on any BLOCK; 2 with strict on REVIEW/UNKNOWN; else 0. Mirrored in the x-census-exit-code header
  - `entries` AuditEntry[]
    - `alias` string
    - `input` object: What was read: url | command, args, type (never env/headers)
    - `server_name` string, nullable
    - `method` 'remote_url' | 'remote_host' | 'npm_package' | 'pypi_package' | 'server_name' | 'null', nullable
    - `decision` 'PASS' | 'REVIEW' | 'BLOCK' | 'UNKNOWN'
    - `reasons` object[]
      - `code` string
      - `result` string
    - `candidates` string[]: Present when resolution was ambiguous; the Census never picks
    - `facts_digest` string, nullable
    - `decision_input_digest` string, nullable
    - `valid_until` string, date-time, nullable
    - `valid_until_epoch` integer, nullable
    - `tools_digest` string, nullable
    - `tools_drift` boolean, nullable
    - `audit_id` string, nullable: Per-entry preflight_evaluation id for keyed callers
    - `lookup_url` string
  - `text` string: The CENSUS-AUDIT/1 text block (also returned alone for Accept: text/plain)
  - `limitations` string[]
  - `meter` object: mode credits (cost, repeat, remaining) or keyless (configs_today, limit)
  - `audit_run_id` string, nullable

## Other responses

- `400`: Closed input validation failed
- `401`: Missing, invalid, or revoked account API key
- `402`: Credit wallet is empty (keyed callers). Body carries credits and upgrade.
- `413`: Body over 256 KB
- `429`: Burst, daily, refresh, or per-server cooldown limit reached

---

[API](https://skmtc.dev/mcpcensus/apis/the-mcp-census-api.md) · [All operations](https://skmtc.dev/mcpcensus/apis/the-mcp-census-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mcpcensus/apis/the-mcp-census-api/revisions/934a7da85b52?raw)