AuditBadger includes a built-in MCP (Model Context Protocol) server that lets AI assistants use your compliance data directly. This gives AI tools real-time access to your projects, controls, documents, sections, and evidences, plus limited document-editing access when your permissions allow it — so you can ask questions, generate reports, update draft policies, or get implementation guidance without copy-pasting.

## **What you get**

The MCP server exposes 13 tools:

* **list_projects** / **get_project** — browse and inspect compliance projects

* **list_controls** / **get_control** — query controls with filters (by project, section, implementation status)

* **list_documents** / **get_document** — access policies, procedures, and other compliance documents (including content)

* **update_document_content** — replace the Markdown content of a document; works only on documents in the editable state (finalized documents need a new version created in AuditBadger first) and requires update permission on that document

* **list_sections** / **get_section** — navigate the section hierarchy within a project

* **list_evidences** / **get_evidence** — review evidence records

* **search** — full-text search across all compliance data (requires Global Search to be enabled)

* **send_feedback** — send feedback about AuditBadger (bug reports, feature requests, questions) straight to the AuditBadger team; useful when the AI assistant gets stuck and wants to tell us where to improve

All data is scoped to your account and respects user permissions. A user connecting via MCP sees exactly the same data they would see in the AuditBadger UI.

## **Prerequisites**

Before setting up MCP, you need:

* **API access enabled** for your account (an admin must turn this on in Account Settings)

* **An API token** for authentication

## **Step 1: Enable API Access**

An account administrator must enable API access:

1. Go to **Account Settings**

2. Find the **API Access** toggle

3. Enable it and save

Without this, all API and MCP requests will be rejected.

## **Step 2: Create an API Token**

1. Click your avatar in the top-right corner and go to **Profile**

2. Navigate to the **API Tokens** tab

3. Enter a descriptive name for the token (e.g., "Codex MCP")

4. Set an expiration period (up to 30 days)

5. Click **Create Token**

6. **Copy the token immediately** — it will only be shown once

Keep this token secure. MCP requests use the same account and permission boundaries as your user account, including limited document-update access where allowed. You can revoke the token at any time from the same page.

## **Step 3: Connect your AI assistant**

Your MCP endpoint URL follows this pattern:

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

Replace `YOUR-SUBDOMAIN` with your actual AuditBadger account subdomain (the part before `.auditbadger.com` when you log in).

The server uses the Streamable HTTP transport (the current MCP standard). All clients listed below support it. If you connected before via the legacy `/mcp/sse` endpoint, update your client configuration — the SSE transport has been retired.

---

### **Codex (CLI and IDE extension)**

Codex supports Streamable HTTP MCP servers with bearer-token authentication. The CLI and IDE extension share the same MCP configuration, so one setup works in both clients.

For a personal setup, keep the server in `~/.codex/config.toml` and store the token in an environment variable:

```
export AUDITBADGER_API_TOKEN="YOUR-API-TOKEN"
​
codex mcp add auditbadger \
  --url https://YOUR-SUBDOMAIN.auditbadger.com/mcp \
  --bearer-token-env-var AUDITBADGER_API_TOKEN
```

Then verify the server is configured:

```
codex mcp list
codex mcp get auditbadger --json
```

You can also edit `~/.codex/config.toml` directly:

```
[mcp_servers.auditbadger]
url = "https://YOUR-SUBDOMAIN.auditbadger.com/mcp"
bearer_token_env_var = "AUDITBADGER_API_TOKEN"
```

For a project-scoped setup, put the same TOML block in `.codex/config.toml` inside the repo. Keep only the URL and environment-variable name there; do not commit the API token. Codex loads project-scoped `.codex/config.toml` only for trusted projects.

After changing the configuration, start a new Codex session or restart the IDE extension. In the Codex terminal UI, run `/mcp` to see active MCP servers.

---

### **Claude Code (CLI)**

Run this command in your terminal:

```
claude mcp add auditbadger \
  --transport http \
  https://YOUR-SUBDOMAIN.auditbadger.com/mcp \
  --header "Authorization: Bearer YOUR-API-TOKEN"
```

This adds a project-scoped configuration. To share it with your team, add `--scope project` which writes to `.mcp.json` at the project root.

You can also create `.mcp.json` manually in your project root:

```
{
  "mcpServers": {
    "auditbadger": {
      "type": "http",
      "url": "https://YOUR-SUBDOMAIN.auditbadger.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-API-TOKEN"
      }
    }
  }
}
```

To use an environment variable instead of a hardcoded token:

```
{
  "mcpServers": {
    "auditbadger": {
      "type": "http",
      "url": "https://YOUR-SUBDOMAIN.auditbadger.com/mcp",
      "headers": {
        "Authorization": "Bearer ${AUDITBADGER_API_TOKEN}"
      }
    }
  }
}
```

Then set `AUDITBADGER_API_TOKEN` in your shell environment.

After adding, verify with `claude mcp list` — you should see "auditbadger" listed.

---

### **Claude Desktop (macOS / Windows app)**

Claude Desktop's config file only supports local (stdio) servers, and its Connectors UI expects OAuth-based remote servers — AuditBadger uses API-token (Bearer) authentication instead. Use the `mcp-remote` bridge:

The `mcp-remote` npm package wraps a remote MCP server into a local stdio process that Claude Desktop can use.

1. Make sure you have Node.js installed (v18+)

2. Open Claude, go to Settings, Developer and Edit config OR

   1. Open your Claude Desktop config file:

      1. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

      2. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

3. Add the following (replace `YOUR-SUBDOMAIN` and `YOUR-API-TOKEN`):

```
{
  "mcpServers": {
    "auditbadger": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SUBDOMAIN.auditbadger.com/mcp",
        "--header",
        "Authorization:${AUDITBADGER_TOKEN}"
      ],
      "env": {
        "AUDITBADGER_TOKEN": "Bearer YOUR-API-TOKEN"
      }
    }
  }
}
```

The token is passed via the `env` section and referenced as `${AUDITBADGER_TOKEN}` in the header argument. The `Authorization:` header uses no space after the colon — this avoids a known issue where some platforms mangle spaces inside `args`.

4. Save the file and restart Claude Desktop

5. You should see "auditbadger" in the tools menu (hammer icon)

---

### **Cursor**

1. Create or edit the file `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global access)

2. Add the following:

```
{
  "mcpServers": {
    "auditbadger": {
      "url": "https://YOUR-SUBDOMAIN.auditbadger.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AUDITBADGER_API_TOKEN}"
      }
    }
  }
}
```

3. Set the `AUDITBADGER_API_TOKEN` environment variable to your API token

4. Restart Cursor

You can also use the Settings UI: open Settings (Cmd+Shift+P, then "Cursor Settings"), go to the **MCP** section, and the JSON editor will show the same file.

Note: Cursor uses `${env:VAR_NAME}` syntax for environment variables (different from Claude Code's `${VAR_NAME}` syntax).

---

### **ChatGPT**

ChatGPT supports MCP servers through developer mode and connectors. This requires a ChatGPT Pro, Plus, Business, Enterprise, or Education plan.

1. Open ChatGPT on the web

2. Go to **Settings** then **Connectors**

3. Click **Create** to add a new connector

4. Enter the MCP endpoint URL: [`https://YOUR-SUBDOMAIN.auditbadger.com/mcp`](https://YOUR-SUBDOMAIN.auditbadger.com/mcp)

5. Follow the authentication configuration steps

Note: ChatGPT connectors may require OAuth-based authentication. If Bearer token auth is not directly supported in the connectors UI, contact your AuditBadger administrator about OAuth setup options.

For more details, see OpenAI's documentation on developer mode and MCP connectors.

---

### **Other MCP Clients**

Any MCP-compatible client can connect using:

* **Transport**: Streamable HTTP (stateless — every JSON-RPC message is a self-contained POST and the response comes back in the same HTTP response)

* **Endpoint**: [`https://YOUR-SUBDOMAIN.auditbadger.com/mcp`](https://YOUR-SUBDOMAIN.auditbadger.com/mcp)

* **Authentication**: `Authorization: Bearer YOUR-API-TOKEN` header on all requests

## **Optional: Enable Global Search**

The MCP server includes a **search** tool that lets AI assistants search across all your compliance data using full-text search. This is much faster than browsing through lists when looking for specific controls or documents.

To enable it:

1. Go to **Account Settings**

2. Find the **Compliance** section

3. Enable the **Global Search** checkbox

4. Save

Note: enabling search indexing stores decrypted content (like document text and implementation notes) in a plaintext search index. This enables full-text search but means that data exists in an additional unencrypted form in the database.

If Global Search is not enabled, the search tool will return a message telling the AI to use the list tools with filters instead.

## **Usage Examples**

Once connected, you can ask your AI assistant questions like:

* "List all my compliance projects and their status"

* "Show me the controls in my ISO 27001 project that are not yet implemented"

* "Find the access control policy document and summarize it"

* "Rewrite the acceptable use policy to cover remote work, and update the document"

* "What evidence do we have for control A.8.1?"

* "Search for anything related to encryption in our compliance data"

* "Give me a progress report on our SOC 2 project"

The AI will use the MCP tools to fetch real-time data from AuditBadger and respond with accurate, up-to-date information.

## **Security and Rate Limits**

* **Data isolation**: MCP respects your account boundaries. You can only access data belonging to your account's subdomain.

* **Permissions**: The MCP server enforces the same role-based permissions as the AuditBadger UI. Users see only what they're authorized to see.

* **Token expiration**: API tokens expire after the period you set (max 30 days). Create a new token when the current one expires.

* **Rate limiting**: MCP requests are throttled to 100 requests per minute per token. Exceeding this returns a 429 (Too Many Requests) response.

* **Brute-force protection**: Repeated unauthenticated requests from the same IP address will be throttled.

* **Limited write access**: The only tools that change anything are `update_document_content` (which edits document content, gated by the editable state and your update permission) and `send_feedback` (which does nothing beyond emailing your feedback to the AuditBadger team). Nothing else can be created, modified, or deleted through MCP.

## **Troubleshooting**

* **"Unauthorized" or connection refused**: verify your API token is correct and has not expired. Check that API access is enabled for your account.

* **Configured before the transport change**: older setups pointed at [`https://YOUR-SUBDOMAIN.auditbadger.com/mcp/sse`](https://YOUR-SUBDOMAIN.auditbadger.com/mcp/sse) with the SSE transport. That endpoint no longer exists — re-add the server with the Streamable HTTP transport and the `/mcp` URL as shown above.

* **Empty results**: make sure you have compliance projects set up in AuditBadger. The MCP tools return data from your account — if there are no projects, controls, or documents, the results will be empty.

* **Search returns "not available"**: Global Search needs to be enabled in Account Settings. Ask an administrator to turn it on.

* **Token expired**: create a new API token from your Profile page and update your MCP client configuration.

* **"Too many requests" (429)**: you've hit the rate limit. Wait a minute and try again, or reduce the frequency of requests.

* **Codex does not show AuditBadger tools**: run `codex mcp list` and `codex mcp get auditbadger --json`, confirm `AUDITBADGER_API_TOKEN` is set in the environment that launches Codex, then start a new Codex session or restart the IDE extension. In project-scoped configs, also confirm the project is trusted.

* **Claude Desktop not connecting**: make sure you're using the `mcp-remote` bridge — Claude Desktop's config file does not support remote servers directly, and the Connectors UI only works with OAuth-based servers.

* **Cursor not picking up changes**: restart Cursor after editing `.cursor/mcp.json`. Check that your environment variable is set in the shell that launched Cursor.