@blacksandscyber/mcp-server-shield

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 Shield directly.

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

| Surface | Install | Effort | |---|---|---| | Claude Code | claude mcp add shield -- npx -y @blacksandscyber/mcp-server-shield | 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 shield.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 shield -- npx -y @blacksandscyber/mcp-server-shield

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

Then, in any Claude Code session:

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

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

Bring your own credentials (full Shield API access)

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

claude mcp add shield \
  --env SHIELD_AUTHORIZER_URL=https://mauth-beta.blacksandscyber.online \
  --env SHIELD_CLIENT_CERT=$HOME/.blacksands/mcp-certs/test-mcp9.crt \
  --env SHIELD_CLIENT_KEY=$HOME/.blacksands/mcp-certs/test-mcp9.key \
  --env SHIELD_AUTH_PASSWORD=$(cat $HOME/.blacksands/mcp-certs/.auth-password) \
  --env SHIELD_ORG_ID=blacksands \
  -- npx -y @blacksandscyber/mcp-server-shield

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

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

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-shield-x.y.z.dxt:

   cd mcp-server-blacksands-shield
   MANIFEST=manifest-v2.json npm run build:dxt
   # outputs build/blacksands-shield-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 shield.blacksandscyber.online/docs/install.

What you get

9 [FREE] tools — no account needed

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

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

36 tools requiring a Blacksands account

Provisioning (shield_create_org, shield_create_app, shield_provision_app, shield_install_agent_remotely), compliance (shield_compliance_report, shield_compliance_controls), certs (shield_list_certs, shield_revoke_cert, shield_rotate_cert), Receiver lifecycle (receiver_initialize, receiver_activate, receiver_onboard_service, receiver_health), sessions (shield_list_sessions, shield_revoke_session), and emergency controls (shield_emergency_lockdown, shield_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 | | SHIELD_AUTHORIZER_URL | https://mauth-beta.blacksandscyber.online | broker mode | Where the MCP client authenticates to Shield | | SHIELD_SETUP_URL | https://onboard.beta.blacksandscyber.online | token bootstrap | Where setup tokens are redeemed | | SHIELD_SETUP_TOKEN | (none) | first-time bootstrap | One-time bss_… token from a Blacksands admin | | SHIELD_CLIENT_CERT | (none) | broker mode | Path to mTLS client cert PEM file | | SHIELD_CLIENT_KEY | (none) | broker mode | Path to mTLS client key PEM file | | SHIELD_AUTH_PASSWORD | (none) | broker mode | Cert bundle's auth password | | SHIELD_ORG_ID | (none) | broker mode | Your organization id | | SHIELD_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 SHIELD_SETUP_TOKEN.

Verifying the install

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

# Quickest check — call a [FREE] tool that doesn't need Shield API
claude --print "What is the Blacksands deployment architecture? Use shield_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-Shield.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-shield
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/shield/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 Shield 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].