Bursar — AI agents

Installing the MCP client

Bursar isn't a package you import into your application — it's an MCP server that Claude (Code or Desktop) runs and talks to over the Model Context Protocol. Registering it is the entry point for giving any AI agent a real, cryptographic identity instead of a shared API key. This article covers registration in more detail than the quick-start version in Installing your first agent identity.

Registering the MCP server

Claude Code — one command, run from anywhere:

claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar

Claude Desktop — drag the signed .dxt bundle onto the Claude Desktop app icon and confirm the install.

Either way, Claude launches the Bursar MCP server itself — there's nothing to npm install into your own project, and no client library your code needs to import. Bursar sits alongside your agent as a server it talks to, not a dependency it links against.

What registration alone gives you

A handful of Bursar's tools — codebase scanning, framework detection, PII discovery, deployment guidance — work immediately after registration, with no Blacksands account and no certificate at all. That's enough to try Bursar out before you decide to connect it to your organization.

What issuance actually provisions

A certificate identity isn't minted by the claude mcp add command alone — issuance happens when you connect the server to your organization, either by redeeming a one-time setup token from your admin or by supplying an existing mTLS cert bundle. At that point, Bursar mints a certificate identity scoped specifically to that agent, tied to your organization, with its own expiration. This is meaningfully different from copying an API key into an environment variable: the identity is agent-specific, it's short-lived by design, and every request made under it is traceable back to that one certificate rather than to a credential that might be shared across a dozen scripts and services.

Unlocking full access with a setup token

To move past the free tools and issue a real certificate identity, register Bursar with a setup token your admin issues you:

claude mcp add bursar \
  --env SHIELD_SETUP_TOKEN=bss_xxxxxxxxxxxx \
  -- npx -y @blacksandscyber/mcp-server-bursar

The server redeems the token once, writes the resulting certificate bundle to ~/.blacksands/mcp-certs/, and reuses it on every relaunch — no further network calls or tokens needed unless you're rotating credentials.

Multiple agents, multiple identities

If you're running more than one agent — say, a build agent and a research agent — register and issue a certificate separately for each. Each agent should get its own certificate identity, not a shared one. This is what makes scoped access possible: see Understanding agent identities and scoped access for why per-agent identity matters and how scoping works in practice. It's also what makes your organization's plan limits meaningful — the number of MCP clients your plan supports corresponds directly to the number of distinct agent identities you can issue (see Understanding your plan limits).

Troubleshooting installation

If the server registers but fails to obtain a certificate, check:

That your organization's plan has remaining MCP client capacity
That the environment running the agent has outbound network access to Blacksands' issuance endpoint
That your setup token hasn't expired or already been redeemed, and that you're connecting to the correct organization if you belong to more than one

See Certificate errors and how to fix them for common failure modes and fixes.