@blacksandscyber/mcp-server-bursar

Zero-trust security operations for AI agents. 45 tools for codebase analysis, application provisioning, mTLS certificate management, compliance reporting, and Receiver proxy lifecycle — exposed through the Model Context Protocol so Claude (or any MCP client) can drive Blacksands Bursar directly.

Two install paths, depending on which Claude surface you use:

| Surface | Install | Effort | |---|---|---| | Claude Code | claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar | One command | | Claude Desktop | Drag-and-drop the signed .dxt bundle | One drag |

Nine tools work without any Blacksands account. Codebase scanning, framework detection, PII discovery, deployment guidance — installed and ready immediately. Sign up at bursar.blacksandscyber.online to unlock the remaining 36 tools (provisioning, compliance, Receiver management).

Claude Code — one-line install

The fastest path. Works in any directory — Claude Code launches the MCP server when needed.

# Local-only mode — 9 [FREE] tools work immediately, no account needed
claude mcp add bursar -- npx -y @blacksandscyber/mcp-server-bursar

# Verify
claude mcp list
# bursar: npx -y @blacksandscyber/mcp-server-bursar - ✓ Connected

Then, in any Claude Code session:

> Scan my project at ~/some-app for security risks
[Claude calls bursar_scan_codebase, returns the security manifest]

> What's the Blacksands deployment architecture?
[Claude calls bursar_guide_deployment, returns the authoritative overview]

Bring your own credentials (full Bursar API access)

To unlock all 45 tools, pass your existing cert bundle (issued through Overwatch / SysAdmin / a setup token):

claude mcp add bursar \
  --env BURSAR_AUTHORIZER_URL=https://mauth-beta.blacksandscyber.online \
  --env BURSAR_CLIENT_CERT=$HOME/.blacksands/mcp-certs/test-mcp9.crt \
  --env BURSAR_CLIENT_KEY=$HOME/.blacksands/mcp-certs/test-mcp9.key \
  --env BURSAR_AUTH_PASSWORD=$(cat $HOME/.blacksands/mcp-certs/.auth-password) \
  --env BURSAR_ORG_ID=blacksands \
  -- npx -y @blacksandscyber/mcp-server-bursar

Or, for a one-time bootstrap with a setup token from your Blacksands admin:

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

The MCP server redeems the token on first launch, persists the cert bundle to ~/.blacksands/mcp-certs/, and uses it for every subsequent run.

Claude Desktop — drag-and-drop the .dxt

1. Build (or download) blacksands-bursar-x.y.z.dxt:

   cd mcp-server-blacksands-bursar
   MANIFEST=manifest-v2.json npm run build:dxt
   # outputs build/blacksands-bursar-x.y.z.dxt

2. Drag the .dxt onto the Claude Desktop app icon.
3. Confirm install. Send a chat message — the MCP server starts on first tool call.

For the non-coder onboarding flow (admin issues a setup token, user clicks the install email), see bursar.blacksandscyber.online/docs/install.

What you get

9 [FREE] tools — no account needed

Run on any local project. No network calls except for bursar_guide_deployment's overview text (which is bundled).

| Tool | What it does | |---|---| | bursar_scan_codebase | Composite scan — framework, endpoints, PII, services, datastores, manifest | | bursar_detect_framework | Express, Flask, Rails, Next.js, Django, etc. | | bursar_scan_endpoints | Extract HTTP/API routes with method + auth detection | | bursar_detect_pii | SSN, credit card, health data, DOB; produces compliance hints | | bursar_detect_external_services | Stripe, OpenAI, AWS, Firebase, Twilio, etc. | | bursar_detect_data_stores | PostgreSQL, MongoDB, Redis, ORMs | | bursar_generate_manifest | Assemble detection results into a Security Manifest JSON | | bursar_get_protection_requirements | Plain-English checklist of what's needed to protect this app | | bursar_guide_deployment | Authoritative deployment walkthrough — DigitalOcean Droplet, local-docker dev, etc. |

36 tools requiring a Blacksands account

Provisioning (bursar_create_org, bursar_create_app, bursar_provision_app, bursar_install_agent_remotely), compliance (bursar_compliance_report, bursar_compliance_controls), certs (bursar_list_certs, bursar_revoke_cert, bursar_rotate_cert), Receiver lifecycle (receiver_initialize, receiver_activate, receiver_onboard_service, receiver_health), sessions (bursar_list_sessions, bursar_revoke_session), and emergency controls (bursar_emergency_lockdown, bursar_lift_lockdown).

Calling any of these in local-only mode returns a friendly setup-token prompt instead of a stack trace.

Configuration

All env vars are optional except where noted. Sensible defaults are baked in so the MCP server starts in local-only mode with zero configuration.

| Var | Default | Required for | Description | |---|---|---|---| | MCP_TRANSPORT | stdio | — | Set to local-only to skip all auth and run only the 9 [FREE] tools | | BURSAR_AUTHORIZER_URL | https://mauth-beta.blacksandscyber.online | broker mode | Where the MCP client authenticates to Bursar | | BURSAR_SETUP_URL | https://onboard.beta.blacksandscyber.online | token bootstrap | Where setup tokens are redeemed | | BURSAR_SETUP_TOKEN | (none) | first-time bootstrap | One-time bss_… token from a Blacksands admin | | BURSAR_CLIENT_CERT | (none) | broker mode | Path to mTLS client cert PEM file | | BURSAR_CLIENT_KEY | (none) | broker mode | Path to mTLS client key PEM file | | BURSAR_AUTH_PASSWORD | (none) | broker mode | Cert bundle's auth password | | BURSAR_ORG_ID | (none) | broker mode | Your organization id | | BURSAR_CA_CERT | bundled | optional | Path to Blacksands CA cert (override the bundled one) | | LOG_LEVEL | info | — | debug, info, warn, error |

Persisted state lives in ~/.blacksands/mcp-certs/:

• <client-name>.crt, <client-name>.key — your mTLS bundle
• .auth-password, .client-name, .org-id, .last-token-prefix — bookkeeping
• blacksands-ca.crt — the Blacksands CA chain

To rotate credentials: rm -rf ~/.blacksands/mcp-certs/, then start the MCP server with a fresh BURSAR_SETUP_TOKEN.

Accessing protected services

Once your agent has a valid mTLS cert (issued by Blacksands), reaching a protected service is NOT a single mTLS call. The auth chain is bisected: agent does mTLS to the Authorizer (which returns a list of services it's allowed to reach), then a SECOND independently-verified mTLS handshake to the Receiver (a public-IP edge proxy that forwards to the actual backend service).

For LLM-generated client code: ask Claude to call broker_get_protocol_walkthrough before generating anything. That tool returns the authoritative protocol description plus copy-paste examples in Node.js, Python, and curl. Don't let Claude improvise the auth chain from training-data assumptions about mTLS — Blacksands is unusual: cert at TWO independent stages, backend service URL never reachable directly.

                  INTERNET
                     │
                     │  443 (mTLS, mandatory)
                     ▼
         ┌────────────────────┐
         │     Authorizer     │  ← step 1: agent mTLS handshake
         │  (mauth-…)         │  ← step 2: returns service-list with Receiver URLs
         └────────────────────┘
                     │
                     │  agent picks service, builds URL with sessionToken
                     ▼
         ┌────────────────────┐
         │     Receiver       │  ← step 4: SECOND mTLS handshake (same cert,
         │  (public IP edge)  │            re-verified independently)
         └─────────┬──────────┘
                   │ private network
                   ▼
              backend service
              (never reachable directly)

The MCP server's broker_get_protocol_walkthrough tool is the canonical reference — fetched lazily when an LLM needs it. Same content is also surfaced as the blacksands://broker-protocol MCP resource for clients (like Claude Desktop) that prime context at session start.

A minimal Node.js sketch:

const agent = new https.Agent({ cert, key, ca });

// STEP 1+2: mTLS to Authorizer, get service URL + token
const auth = await axios.post(
  'https://mauth-beta.blacksandscyber.online/api/agent/auth',
  { password, serviceId: 'bursar-api' },
  { httpsAgent: agent }
);
const receiverUrl = auth.data.service.serviceUrl;  // points at the Receiver, not the service
const [base, qs] = receiverUrl.split('?');
const token = new URLSearchParams(qs).get('token');

// STEP 3+4+5+6: SAME agent reused for the second mTLS handshake
const api = axios.create({
  baseURL: `${base}/v1`,
  httpsAgent: agent,        // same cert presented again, Receiver re-verifies independently
  params: { token },
});
const orgs = await api.get('/orgs');

Full Node.js, Python, and curl examples — plus the anti-patterns to avoid — are in the tool's output.

Verifying the install

# Should show "bursar: ... ✓ Connected"
claude mcp list

# Quickest check — call a [FREE] tool that doesn't need Bursar API
claude --print "What is the Blacksands deployment architecture? Use bursar_guide_deployment."

The MCP server logs to stderr (stdout is reserved for the MCP wire protocol). On macOS look in ~/Library/Logs/Claude/mcp-server-Bursar.log (Claude Desktop) or run with claude --mcp-debug (Claude Code).

Development

git clone https://github.com/b0bmarl3y/Blacksands_2_0.git
cd Blacksands_2_0/mcp-server-blacksands-bursar
npm install
npm run lint && npm test          # 137 tests, ~4s
npm run build                     # tsc → build/
node dxt/scripts/setup.js         # boot the server directly

Test harness layout:

| Tier | Location | What it covers | Cadence | |---|---|---|---| | 1 | tests/manifest.test.ts, tests/dxt-package.test.ts, tests/bursar/deploy/*, tests/config.test.ts, tests/server-tags.test.ts | DXT manifest spec, content invariants on tool output, mode dispatch, [FREE] tag discipline | Every commit | | 2 | tests/harness/* | MCP wire-protocol harness — spawns the compiled server and exercises tools/list + tools/call against a fixture project | Every PR | | 3 | tests/integration/live-broker.test.ts (gated) | Live broker chain canary against the real Bursar API | Release / on-demand (RUN_LIVE_INTEGRATION=1) | | 4 | (manual checklist) | Drag-install validation + LLM behavior + destructive-tool exercise | Release prep |

License

MIT — see LICENSE.

For commercial support, custom integrations, or enterprise deployments (cryptographic remote attestation, HSM-backed cert storage, on-prem control plane), contact [email protected].