MCP server

Four read-only tools that let an agent or a reviewer ask VIGIL about trust without touching the database. The server talks to the HTTP API with a bearer key and nothing else. Code: mcp_server/.

Tool	Returns
get_trust(agent_id)	Latest BII, the four signals, composite trust, and the agent's current gate (status, action id, reason, review outcome)
list_holds()	Enforcement actions awaiting review in your org, newest first. Reads GET /holds on the gate service when VIGIL_GATE_URL is set, otherwise GET /enforcement/pending on the API
explain_score(agent_id)	The four signals with one plain sentence each on what moved them, computed from the last 50 audit entries and the latest score
verify_chain(agent_id)	GET /audit/{agent_id}/verify: ok, length, head, first_bad_seq, agent_records

Errors come back as {"error": "not_found" | "unauthorized" | "forbidden" | "rate_limited" | "upstream_error", "status", "detail"} so a calling agent can read them instead of crashing. There is no tool that writes anything.

Run

pip install -r requirements.txt          # includes mcp>=1.2,<2
export VIGIL_API_URL=https://vigil.supertruth.ai
export VIGIL_API_KEY=vg_...              # scope read; admin or review if you set VIGIL_GATE_URL
export VIGIL_GATE_URL=https://gate.vigil.supertruth.ai   # optional
python -m mcp_server                     # stdio
python -m mcp_server --http              # streamable HTTP on 127.0.0.1:8765 (MCP_HOST, MCP_PORT)

Claude Code and Claude Desktop

.mcp.json in a project (Claude Code) or claude_desktop_config.json:

{
  "mcpServers": {
    "vigil": {
      "command": "/path/to/vigil/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/vigil",
      "env": {
        "VIGIL_API_URL": "https://vigil.supertruth.ai",
        "VIGIL_API_KEY": "vg_...",
        "VIGIL_GATE_URL": "https://gate.vigil.supertruth.ai"
      }
    }
  }
}

Then ask: "What is the trust score for agent jaybot?", "Anything on hold?", "Why did jaybot drop?", "Does the ledger verify?"

What the tools call

get_trust and verify_chain are thin wrappers. Here are their two API calls for the quickstart agent, so you can see exactly what the tool returns to the model:

curl -sf -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/scores/docs-quickstart/latest"
curl -sf -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/audit/docs-quickstart/verify"

Run the quickstart first so the agent exists.