Connect AI agents (MCP)

Get an API token

1. Open Settings → API tokens. The API comes with the free trial and the Team, Business and Enterprise plans, not Solo.
2. Name the token after the agent that will use it. Turn on Allow printingonly if the agent should print badges; it’s off unless you turn it on. Click Create, and copy the token. It’s shown only once.
3. A token belongs to one organization, and every request made with it reads and changes that organization only. Revoke it on the same page when the agent no longer needs it.

Base URL

REST requests go to https://hq.badgebadger.app/api/v1, with the token in an Authorization: Bearer bsk_... header. The endpoints are listed in API and webhooks.

OpenAPI description

The REST API is described in OpenAPI 3.1 at https://hq.badgebadger.app/api/v1/openapi.json. Reading it doesn’t take a token. Import it into an API client, or into an agent framework that builds tools from OpenAPI.

Connect an MCP client

The MCP server is at https://hq.badgebadger.app/api/mcp. It uses the Streamable HTTP transport and takes the same API token in the Authorization header. It doesn’t offer OAuth sign-in, so use a client that lets you set that header.

Claude Code

claude mcp add --transport http badgebadger https://hq.badgebadger.app/api/mcp \
  --header "Authorization: Bearer bsk_..."

Then run /mcp in Claude Code to check that it connected.

Cursor

Add this to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project, and set BADGEBADGER_TOKEN in your environment to the token:

{
  "mcpServers": {
    "badgebadger": {
      "url": "https://hq.badgebadger.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BADGEBADGER_TOKEN}"
      }
    }
  }
}

VS Code

Add this to .vscode/mcp.json. VS Code asks for the token when the server first starts, so it isn’t saved in the file:

{
  "servers": {
    "badgebadger": {
      "type": "http",
      "url": "https://hq.badgebadger.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:badgebadger-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "badgebadger-token",
      "description": "BadgeBadger API token",
      "password": true
    }
  ]
}

Other clients

Any MCP client that connects over Streamable HTTP and can send a custom Authorization header can use the URL and token above.

What the tools do

Each tool runs the same code as the matching REST endpoint and answers with the same JSON.

• list_employees: every employee, like GET /api/v1/employees. There’s no search or paging, so the whole roster comes back in one result.
• upsert_employees: create or update up to 1,000 employees, matched on employee_id, like POST /api/v1/employees.
• list_templates: your badge templates, like GET /api/v1/templates.
• list_print_jobs: recent print history, newest first, like GET /api/v1/print-jobs.
• list_printers: your paired print computers, their printers, and which are online, like GET /api/v1/printers.
• print_badges: print cards for up to 25 people, like POST /api/v1/print-jobs. It only works with a token created with printing allowed.
• get_print_job: whether a print is waiting for approval, queued, printing, printed or failed, like GET /api/v1/print-jobs/{id}.

Every MCP request counts against the token’s per-minute API limit, including the few a client sends when it connects.

Printing from an agent

print_badges prints real cards on your card printer, so it uses card stock and ribbon. These limits apply whatever the agent asks for:

• Printing is off for every token. An admin turns it on for one token when creating it, and can turn it off later. Turning it off, or revoking the token, cancels its prints that haven’t started.
• At most 25 cards per call, and 200 cards an hour and 1,000 a day per organization through the API, prepared 2 at a time. The free trial stops at 10 printed cards, as it does in the app.
• The same pre-flight check as the app runs first. A card with a problem that blocks it isn’t printed, and warnings such as a missing photo need the agent to confirm.
• If your organization requires print approval, the print waits for an admin to approve each card on the Approvals page.
• Every print is in the audit log, and your organization’s admins get a notification naming the token, the number of cards and the printer.
• print_badges needs an idempotency_key, a new one for each print. The same key within 24hours returns the first print instead of printing again, so an agent that retries a call can’t print twice.

The print goes to a paired computer that shares its printers and is online. If there’s exactly one, the agent doesn’t need to name it; otherwise it picks one from list_printers.