---
title: "API & MCP server"
canonical: "https://auditbadger.com/features/api-and-mcp/"
last-updated: "2026-09-03"
---

# API & MCP server

AuditBadger has two machine surfaces. The REST API writes directly with a human-owned token, for integrations you build and operate. The MCP server at `/agent/mcp` is for agents: it reads everything its token is scoped to and proposes changes that a person in the account reviews and approves. Both are included at $250/month flat.

## MCP server

| | |
|---|---|
| Endpoint | `https://{account}.auditbadger.com/agent/mcp` (Streamable HTTP, stateless) |
| Auth | `Authorization: Bearer <agent token>`; personal API tokens are rejected with `401 agent_token_required` |
| Tools | 118 total: 58 reads, 49 propose operations, 3 lifecycle, 2 upload, 6 deprecated aliases |
| Writes | None. Every mutation is a change-set proposal a human approves before apply |
| Scopes | Per module: Projects, Controls, Evidence, Documents, Risks, Checks, Vendors, Business continuity, Assets, ISMS workbook. Read, or read and propose |
| Tokens | Named, revocable, rotatable, max 365 days, issued under Profile > Agent tokens |
| Discovery | `whoami` (scopes, operations, protected actions, limits), `describe_operations` (exact schemas) |
| Outcomes | Poll `get_change_set` (stable codes, `retryable`, `next_action`) or HMAC-signed webhooks on 7 lifecycle events |
| Uploads | PNG, JPEG, GIF, WebP, PDF; 10 MB/file; checksum-verified; PDFs with active content refused, image metadata stripped |
| Limits | 100 req/min per token; 25 items per change set; 20 open sets per token; proposals expire after 14 days |

Full server card with all 118 tool names: [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json)

## REST API

| | |
|---|---|
| Base URL | `https://{account}.auditbadger.com/api/v1/` |
| Auth | `Authorization: Bearer <API token>`, issued under Profile > API Tokens, max 30 days |
| Spec | [/openapi.json](/openapi.json) (YAML at [/api/openapi.yaml](/api/openapi.yaml)), reference at [auth.auditbadger.com/api/v1/docs](https://auth.auditbadger.com/api/v1/docs) |
| Coverage | Projects, sections, controls, evidence with attachments, documents, document series |
| Writes | Direct, under the token owner's permissions, audit-logged |

Keep API tokens with people: an API token acts as its owner and writes directly. An autonomous agent should carry an agent token instead, so the proposal-and-review boundary applies.

## Guardrails

- Stale reads refused: proposals must carry the versions the agent observed (`version_stale` → read again, repropose)
- Idempotency keys on every mutation and lifecycle call: retries and replays cannot duplicate effects
- Protected actions (evidence verification, sign-offs, Trust Center publishing) have no agent tool
- Explicit-judgment operations require per-item human confirmation, never bulk approval
- Strict tenant isolation: foreign record IDs fail without disclosing existence
- Per-token and per-IP rate limits; repeated invalid bearers ban the IP

## Useful links

- The offering explained: [/headless-compliance](/headless-compliance)
- Developer hub: [/developers](/developers)
- Credentials: [/auth.md](/auth.md)
- Agent instructions: [/agents.md](/agents.md)
- All features: [/features](/features)