MCP Server — Connect AI Assistants to Humadroid

AuditBadger has a built-in MCP (Model Context Protocol) server. Connect Claude, ChatGPT, Claude Code, Codex, Cursor, or any MCP client that understands MCP authorization, and the assistant can read your compliance data and propose changes to it.

The endpoint is:

https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp

Replace YOUR-SUBDOMAIN with the subdomain you log in on. That is all a client needs: it discovers the sign-in flow on its own, sends you to AuditBadger to choose what it may access, and returns with its own credential. There is no token to copy.

The one rule worth knowing

The assistant never writes. There is no tool on this server that changes a record.

Every write is a proposal. The assistant assembles one or more intended changes into a change set, and that change set sits in a review queue until a person in your account opens it and decides — item by item, or approving the safe ones together. Only after a human decision does AuditBadger apply anything, and it applies it under that person's own permissions, against the exact record state the assistant said it had observed.

That gives you three things an ordinary AI integration does not:

A gate. An assistant that misunderstands your policy produces a rejected proposal, not a wrong record.
A diff. The review screen shows what each item would change, the assistant's stated reason, and where it says the information came from.
An audit trail. Every applied change carries the agent channel, the connection that proposed it, the change set it came from, and the person who approved it. Filter the audit log by channel to separate assistant changes from what people did in the browser.

There is one deliberate exception, off by default, described under Letting an agent approve its own safe changes.

Before you start

API access must be enabled for your account. An administrator turns this on in Account Settings; without it every MCP request is rejected and the consent screen refuses.
You must be an active member. Connections are personal: the assistant acts under your name, with the access you chose, and only you (or an account administrator) can revoke it.

Step 1: Connect your client

The Connect your client panel under Profile → Connected agents carries the same instructions with your own subdomain already filled in.

Every client below ends on the same AuditBadger consent screen, described in Step 2.

Claude.ai and Claude Desktop

Open Settings → Connectors → Add custom connector.
Name it AuditBadger and paste the endpoint as the remote MCP server URL. Leave the client ID and secret fields empty.
Click Connect. The consent screen opens; after you allow access the connector shows as connected and its tools are available in new chats.

Custom connectors exist only on the plans that offer them. If the option is missing, your plan or your organization administrator does not allow them.

ChatGPT

Open Settings → Connectors and turn on Developer mode under Advanced if it is not on already.
Choose Create, name it AuditBadger, paste the endpoint as the MCP server URL, select OAuth, and create. The consent screen opens in your browser.

Claude Code (CLI)

claude mcp add auditbadger --transport http https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp

Add --scope project to write .mcp.json at the project root and share the configuration with your team. It holds no secret:

{
  "mcpServers": {
    "auditbadger": {
      "type": "http",
      "url": "https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp"
    }
  }
}

In a session, run /mcp, pick auditbadger, and choose Authenticate. Your browser opens the consent screen. Each team member authenticates once on their own machine.

Codex (CLI and IDE extension)

codex mcp add auditbadger --url https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp
codex mcp login auditbadger

The second command opens your browser for the consent screen. Start a new session afterwards and confirm with codex mcp list.

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "auditbadger": {
      "url": "https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp"
    }
  }
}

In Cursor Settings → MCP the server shows Needs login. Click it and allow access on the consent screen.

Any other MCP client

Transport: Streamable HTTP, stateless
Endpoint: https://YOUR-SUBDOMAIN.auditbadger.com/agent/mcp
Authorization: standard MCP authorization. An unauthenticated request receives 401 with a WWW-Authenticate challenge naming the protected-resource metadata; from there the client finds the authorization server, registers itself (dynamic registration or a client ID metadata document), and runs an authorization-code flow with PKCE. Refresh tokens are issued and rotate.
A client that does not understand MCP authorization can send a static agent token instead. See Static tokens.

Most clients also let you control which tools are exposed to the model and which run without a prompt. Reviewing that list is worth the five minutes: this server is proposal-only, so an always-allow setting cannot cause a write on its own, but it can cause a queue full of proposals nobody asked for — and if you enabled agent approval, the safe ones among them get applied.

Step 2: The consent screen

The client sends you to a page on your own AuditBadger subdomain. You must be signed in there as yourself. The page names the client and where it will return you, and asks three things.

Access per module. Access is set separately for each compliance module: Projects, Controls, Evidence, Documents, Risks, Checks, Vendors, Business continuity, Assets, ISMS workbook, and People. Each module gets one of three levels:

No access — the assistant cannot see the module at all.
Read — it can read that module and nothing else there.
Read and propose — it can read, and it can propose changes for review. Propose always includes read.

If the client asked for specific access, that is preselected; otherwise every module starts at Read. Change it freely, and give the connection only the modules the job needs. The assistant can call whoami at any time to see exactly which scopes it holds, and whether it is connected through OAuth or a static token.

Expiry. The default is 30 days and the maximum is 365. After that date the client must ask again, and you get this screen again. Pick the shortest window that fits how you work.

Whether the agent may approve its own safe changes. Off unless you type the acknowledgement. See the next section before you do.

Click Allow access and you return to the client. Click Deny and the client is told you declined; nothing is recorded.

Connecting the same client again replaces the previous connection: the old one is revoked the moment the new one is granted, so there is never more than one live grant per client and person.

Letting an agent approve its own safe changes

By default you approve everything. There is an opt-in, per connection, that changes this: the agent may approve its own proposals, without you opening the review queue.

It is deliberately narrow:

Only that connection's own proposals. One agent cannot clear another's queue.
Only reversible, bulk-safe changes. Judgment calls — risk assessments and treatment decisions, control implementation status, policy publication, evidence submission, vendor assurance reviews, unlinking infrastructure, check acceptances — are never eligible, whatever you agreed to. A set containing one is refused whole, so it comes back to you intact rather than half-decided.
Anything your own review would hide from you is not yours to delegate; that set is refused too.
The delegation lives on the connection and dies with it. Revoke it, let it expire, or reconnect the client, and the delegation is gone; there is nothing separate to remember to switch off.

To enable it you type the sentence I understand the audit consequences on the consent screen, or later under Profile → Connected agents. That is the point of the exercise, and the consequence is real: your approval is recorded once, here, instead of once per change. Over MCP there is no record of what you asked the agent for, so the agent is the only witness that you asked for it. Every change it approves is still recorded against you by name, and carries the agent_delegated channel so an auditor can tell those apart from decisions you clicked.

When the agent approves a set this way it must pass a user_statement: what you actually said when you asked for it. That sentence is recorded as the decision note on every item in the set, and it is the only evidence of your intent that this surface has — so it is worth reading back afterwards to check the agent recorded what you said rather than what it inferred.

Turning it off asks for nothing. Withdrawing trust should never be harder than granting it.

Managing connections

Profile → Connected agents lists every connection you granted: the client, the access you chose, the expiry, when it was last used, and whether agent approval is on. Revoke from there. It takes effect immediately: the client's tokens stop working, and any change sets it proposed that nobody has decided yet are cancelled. Work a human already approved still completes.

Account settings → Connected agents shows administrators every connection in the account, across all members, with the same revoke action. Administrators cannot connect on someone else's behalf; consent is always the member's own.

A client can also disconnect itself. When it does, the connection is revoked here as well, on the agent channel, so the list always shows the truth.

Connections are never deleted, only revoked, so the history of what each one did stays readable.

Static tokens (advanced)

Some runtimes cannot open a browser: a script, a CI job, a server-side agent framework. For those, a static agent token does what a connection does, with a secret you carry yourself. Find it under Profile → Connected agents, in the Static tokens (advanced) section at the bottom.

Give the token a name. Names are unique across your whole account, including revoked ones.
Add a description saying where it will be used. It is stored encrypted.
Set the expiry: 30 days by default, 365 at most.
Choose access per module, exactly as on the consent screen, then create the token.
Copy the secret immediately. It is shown once and cannot be recovered.

Send it on every request:

Authorization: Bearer YOUR-AGENT-TOKEN

The token is only ever read from that header. Query parameters, cookies, and alternate headers are not consulted.

Static tokens can be rotated (a replacement is issued and the old token revoked in one step, with a new name and expiry) and revoked, from the same page. To change a static token's scopes, rotate it. Agent approval can be enabled on a static token too, with the same acknowledgement.

Client configuration for a static token is the OAuth configuration plus the header. Claude Code takes --header "Authorization: Bearer YOUR-AGENT-TOKEN"; Codex takes --bearer-token-env-var; Cursor takes a headers object with ${env:VAR}. Keep the secret in an environment variable, never in a committed file.

Migrating from the old MCP endpoint

The old endpoint is gone. https://YOUR-SUBDOMAIN.auditbadger.com/mcp, the one authenticated with a personal API token, was retired on 2026-08-22 and replaced by /agent/mcp. There is no compatibility window. A client that still calls it receives a JSON-RPC error (not a 404) explaining the retirement and naming /agent/mcp, so an assistant connected to the old URL can tell its user exactly what to do.

Your REST API is unaffected. The v1 REST API at /api/v1 keeps its API tokens and its behaviour exactly as they were.

To migrate:

1. Reconnect. Point the client at /agent/mcp with no header, and sign in through the consent screen. Your existing API token will not authenticate against /agent/mcp — it returns 401 agent_token_required, by design, because a human's credential should not be what an autonomous agent carries.

2. Update your prompts. The reads gained a lot of company: 65 now, against 13 before, covering risks, checks, business continuity, assets, the ISMS workbook, and the review pipeline itself. Two renames matter:

list_evidences is now list_evidence. Calling the old name returns tool_renamed naming the replacement.
search is not on this server. Use the list tools with filters. send_feedback emails product feedback to the AuditBadger team directly, without review.

The six old write tools are still callable under their old names as deprecated aliases, so an existing prompt keeps working — but they now propose rather than write. Their replacements:

create_vendor → vendor_create
update_vendor → vendor_update
update_control → control_update_metadata
update_document_content → document_update_content
record_vendor_assurance_review → vendor_record_assurance_review
update_control_implementation → control_update_implementation_notes for notes, or control_update_implementation for status. Send one or the other, never both.

3. Expect a different rhythm. A prompt that used to say "mark control A.8.1 implemented" and get a confirmation now gets a proposal receipt and a change set id. The assistant should read first, propose with the versions it read, then poll for the outcome — and tell you there is something waiting for review.

4. Tell your reviewers. Proposals arrive in a queue and notify by email. If nobody is watching that queue, the assistant's work quietly expires after 14 days.

Historical changes stay put. Anything written through the old endpoint is still in your audit log under the mcp channel.

Troubleshooting

The client never opens a sign-in page — check that the URL ends in /agent/mcp on your own subdomain, and that the client supports MCP authorization. If it does not, use a static token.
The consent screen says API access is off — an administrator enables it in Account Settings.
The consent screen sends you to sign in — you are signed in to a different AuditBadger account than the one in the URL, or not at all. Sign in on that subdomain and retry from the client.
401 on every request — the connection expired or was revoked, API access was disabled, or your membership is no longer active. Reconnect from the client. The 401 is deliberately identical in all these cases.
invalid_grant on refresh — the connection behind the token has ended. Reconnect from the client.
401 after migrating — you are still sending an API token. Remove the header and reconnect, or issue a static agent token.
Client points at /mcp — that endpoint no longer exists. Update the URL to /agent/mcp.
429 — wait for Retry-After. If it persists with light usage, you are probably sharing an egress address and hitting the per-IP ceiling.
Requests blocked entirely — an IP that presented 30 rejected bearers in 10 minutes is banned for 30 minutes. Fix the client first, then wait it out.
503 with Retry-After: 60 — ingress is paused for maintenance. Retry in a minute.
The assistant says it changed something but nothing changed — it proposed. Open the review queue; it is waiting for you.
Proposals refused as stale — something else is editing the same records. Have the assistant read immediately before proposing.
A multi-item set refused as conflicting_items — one item writes a resource another item observed; item_position names the item to move to its own set and detail the shared resource.
Uploads refused — check the type against the allowlist, then the size, then whether the connection has a propose scope for evidence or vendors. upload_active_content means a PDF carried script or actions; flatten it.

Next: the tools and the review flow

This page covered connecting. What the assistant can actually do — the tools, the proposal-and-review rhythm, file attachments, limits, and error codes — is the second part of this guide: https://help.auditbadger.com/hc/auditbadger-help-center/articles/1788254081-mcp-server-tools-review-flow-and-limits