Installing your first agent identity

With a plan selected, the fastest way to see Blacksands working end-to-end is to give an AI agent its first identity. This is a Bursar workflow, and for most developers it comes down to a single command.

Register the MCP server

From Claude Code, in any directory:

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

This registers Bursar — the same MCP server referenced throughout our docs and the Installing the MCP client article — with Claude. (Using Claude Desktop instead? Drag the signed .dxt bundle onto the app icon.) Bursar isn't a library your project installs; it's an MCP server Claude runs and talks to, so this one command is everything your project needs.

Registering the server on its own unlocks a handful of free tools with no account required. Certificate-based identity issuance — the part that actually connects the agent to your organization — happens when you redeem a one-time setup token from your admin:

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

Rather than handing your agent a static API key or a shared credential, redeeming the token is what triggers Bursar to mint it a cryptographic identity tied to your organization.

Why a certificate instead of a key

A static API key is a secret you have to protect forever — if it leaks, it's valid until someone manually rotates it, and it usually can't tell you which agent used it. A certificate identity is different: it's short-lived, it's scoped to a specific agent, and every access request made under it is written to Bursar's access ledger. If a certificate is compromised or an agent is decommissioned, you revoke that one identity — nothing else on the platform is affected.

What "first identity" means in practice

The first time the setup token is redeemed, Bursar issues the agent a certificate scoped to your organization and writes the bundle to ~/.blacksands/mcp-certs/ for reuse on every relaunch. From that point forward, the agent's requests to resources you've configured go through Bursar's brokerage step (see Understanding agent identities and scoped access) — every call is checked against a live grant, not a standing credential.

Verifying it worked

After registering the server and redeeming a setup token, you should see the agent's identity listed in your organization's console, along with its certificate's issue date and expiration. If you don't see it appear, double-check that:

• Your plan has remaining MCP client capacity (see Understanding your plan limits)
• Your organization is fully created and verified (see Creating your Blacksands account)
• You're running claude mcp add in an environment with outbound network access to Blacksands' issuance endpoint, and your setup token hasn't already been used or expired

If the identity still doesn't appear, see Certificate errors and how to fix them.