@shieldlabs-ai/mcp

MCP server that lets AI assistants read ShieldLabs identifications, search their history, explain Risk Scores and verify webhook signatures.

How it fits

1. Browser. The ShieldLabs agent runs an identification and hands your page a request ID.

2. Your backend. It sends the request ID with the protected action (signup, login, checkout) and reads the verdict from the History API, or receives it in a signed identification.scored webhook.

3. Decision. Your backend acts on the Risk Score, the three risk bands, the detection flags and the identifiers (for example, how many accounts one device has opened).

This server puts steps 2 and 3 in reach of an MCP client such as Claude Desktop, Claude Code, Grok, Cursor or VS Code: ask "review request 02f1d973-..." or "which accounts used this device?" and the assistant reads the answers from the History API. Every tool is read-only. New to ShieldLabs? Start free at app.shieldlabs.ai.

Related MCP server: cryptbrew-mcp

Install

npx -y @shieldlabs-ai/mcp

Node.js 20 or later. The server speaks stdio by default; MCP clients start it for you (see Quick start). A container image is published as ghcr.io/shieldlabs-ai/shieldlabs-mcp.

Quick start

1. Copy the Private API Key (sec_...) of your domain from the analytics dashboard at app.shieldlabs.ai. It reads the identifications of that one domain.

2. Add the server to your client.

   Claude Code

   claude mcp add --transport stdio shieldlabs --env SHIELDLABS_API_KEY=sec_your_private_key -- npx -y @shieldlabs-ai/mcp

   Grok (the same local server; ~/.grok/config.toml or .grok/config.toml)

   grok mcp add shieldlabs -e SHIELDLABS_API_KEY='${SHIELDLABS_API_KEY}' -- npx -y @shieldlabs-ai/mcp

   [mcp_servers.shieldlabs]
   command = "npx"
   args = ["-y", "@shieldlabs-ai/mcp"]
   env = { SHIELDLABS_API_KEY = "${SHIELDLABS_API_KEY}" }

   Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and other clients that use the mcpServers format:

   {
     "mcpServers": {
       "shieldlabs": {
         "command": "npx",
         "args": ["-y", "@shieldlabs-ai/mcp"],
         "env": { "SHIELDLABS_API_KEY": "sec_your_private_key" }
       }
     }
   }

   VS Code (.vscode/mcp.json), with the key requested at start-up:

   {
     "inputs": [
       { "type": "promptString", "id": "shieldlabs-api-key", "description": "ShieldLabs Private API Key", "password": true }
     ],
     "servers": {
       "shieldlabs": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@shieldlabs-ai/mcp"],
         "env": { "SHIELDLABS_API_KEY": "${input:shieldlabs-api-key}" }
       }
     }
   }

3. Ask: "Review the ShieldLabs request <request ID>", or run the review_request prompt.

More client setups, HTTP and Docker: examples/.

Hosted server (preview)

ShieldLabs also runs this server for you at https://mcp.shieldlabs.ai/mcp (streamable HTTP). There is nothing to install: add the URL to your MCP client and sign in with your ShieldLabs account when the client opens the sign-in page. The client then holds a short-lived access token (one hour) and refreshes it by itself.

In this release the hosted server connects your account and offers one tool, shieldlabs_check_connection, which confirms that the connection works. The tools that read identifications arrive on the hosted server in a later release; until then, use the local server above. Sign-in is the only way in for now: the hosted server does not accept API keys yet.

Claude: Customize > Connectors > Add custom connector, with the URL https://mcp.shieldlabs.ai/mcp.

Claude Code: add the server, then run /mcp and choose Authenticate:

claude mcp add --transport http shieldlabs https://mcp.shieldlabs.ai/mcp

Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json):

{ "mcpServers": { "shieldlabs": { "url": "https://mcp.shieldlabs.ai/mcp" } } }

{ "servers": { "shieldlabs": { "type": "http", "url": "https://mcp.shieldlabs.ai/mcp" } } }

See examples/hosted for client files. To run the hosted mode yourself, see Deploy the hosted server.

Guide

Review one request

Give the assistant the request ID your backend received with a signup, login or payment. shieldlabs_get_identification reads the verdict, and shieldlabs_explain_risk_score explains the band, each weighted risk signal and the detection flags in plain language. The review_request prompt runs these steps and ends with a suggested action (allow, step-up challenge, manual review or block) and the reasons.

Scoring is asynchronous: the History row appears about 1 to 3 seconds after the browser call and can be refined for up to about 10 seconds while follow-up checks finish. shieldlabs_get_identification waits for a brand-new identification (up to about 10 seconds in total) and returns the first version of the row it finds, so a verdict read in those first seconds can still be refined: read it again (wait: false is enough) once observed_at is about 10 seconds in the past for the final state. Integrations that start the identification when the user begins the action (for example on the first interaction with the form) find the row stored by the time the form arrives.

A request ID that is not found means the identification is unverified, never clean: it may be too new, it may come from another domain (a Private API Key reads one domain), or it was issued while the visitor IP was over the ingest rate limit (such request IDs are never stored).

Investigate an account, a device or an IP address

shieldlabs_summarize_entity aggregates the recent identifications of one User HID, device ID, visitor ID, cookie ID or IPv4 address: distinct devices, accounts, visitors, countries, IP addresses and connection types (with the most frequent values), the highest and average Risk Score, the worst band, rate-limit markers, and the detection flags and risk signals seen, with counts. The result is labelled as computed from the returned history window, not as a ShieldLabs verdict. It reads the 100 most recent identifications by default (max_items, at most 500; each 100 cost one History API request). shieldlabs_search_history lists the individual identifications with paging.

Typical questions:

The investigate_user prompt chains these lookups for one User HID. Account counts leave out the User HID values that do not name an account: null, "anonymous", "fail", "-1" and "unknown".

User HIDs travel as one URL path segment, so a User HID that contains / cannot be searched: the tools refuse it with an explanation instead of returning an empty page (as they refuse . and ..). User HIDs made of URL-safe characters, such as the hex output of userHid() in the server SDKs, avoid this.

Debug a webhook endpoint

shieldlabs_verify_webhook_signature checks a received delivery: the raw body, the X-Shield-Signature header and the endpoint secret (or SHIELDLABS_WEBHOOK_SECRET). When the signature does not match, it tests the usual mistakes (a re-serialized or pretty-printed body, decoded & escapes, an added newline) and tells you which one explains the mismatch. It never returns a secret or an expected signature.

While you rotate an endpoint's secret, give both secrets separated by commas, in the argument or in SHIELDLABS_WEBHOOK_SECRET (for example whsec_new_secret,whsec_old_secret). The delivery is valid when any of them matches, and matched_secret says which one did.

ShieldLabs sends one delivery per identification today, with a 1-second timeout and no retries. Later releases add retries that resend identical bytes, so make the handler idempotent on data.request_id and answer 2xx within 1 second. Use the History API for guaranteed reads and for the latest state: a History row can be refined after the webhook was sent, and the webhook is not sent again.

Plan an integration

The integrate_shieldlabs prompt loads the ShieldLabs setup skill and walks the assistant through the browser identification, the server-side verdict, webhooks and a verification checklist. On stdio it fetches the skill from the shieldlabs-skills release this server version was tested with (tag v1.0.0, never a branch), with a 3-second timeout and a 200 KB limit. It uses its built-in guide when that fails, with --offline, and always over HTTP.

Run over HTTP

SHIELDLABS_API_KEY=sec_your_private_key SHIELDLABS_MCP_TOKEN=your_long_random_token \
  npx -y @shieldlabs-ai/mcp --transport http --port 8787

The endpoint is http://127.0.0.1:8787/mcp (streamable HTTP, stateless, JSON responses). Every request needs Authorization: Bearer <SHIELDLABS_MCP_TOKEN>; when the variable is unset, the server generates a token and prints it once to stderr. GET /health answers {"status":"ok"} without authentication. Over HTTP the integrate_shieldlabs prompt always uses its built-in guide. See examples/http.

Limit the tools

--tools exposes only the tools you list, with or without the shieldlabs_ prefix:

npx -y @shieldlabs-ai/mcp --tools get_identification,explain_risk_score

The identification resource follows shieldlabs_get_identification, and the prompts only mention tools that are exposed.

Reference

Configuration

Tools

Every tool is annotated readOnlyHint: true, destructiveHint: false, idempotentHint: true, accepts response_format (markdown by default, or json) and returns structured content with an output schema. Responses stay under 25,000 characters, in the text and in the structured content: long pages are shortened with a notice and a next_offset to continue, and values longer than 1,000 characters as serialized in JSON (for example a landing URL reported by a browser) are cut and listed in truncated_fields. Invisible and control characters in values (zero-width and bidirectional characters, Unicode tag characters, variation selectors) are replaced by visible \uXXXX or \u{XXXXX} escapes and listed in escaped_fields, so a value cannot hide text from the person reading the output. A cut or escaped value differs from the stored one: do not search by it.

Identifications follow the model of the ShieldLabs server SDKs (webhook field names) without the raw payload, plus risk_band. signals[].description is always null: the History API's score details are internal text, so this server returns the signal slug and weight, as webhooks do.

Resources

Prompts

Reading the results

• Risk Score: integer 0-100. Bands: trusted 0-29, suspicious 30-59, dangerous 60-100. A value above 100 (sent as 999) is the rate-limit marker: the visitor IP was temporarily banned after too many identifications. It is not a score and not a band.

• Risk signals are the weighted reasons behind a score. Weights can be negative (a late network check corrects an earlier one) and signal names are an open set. Branch on risk_score and detection_flags; never add up weights yourself.

• Identifiers: device_id survives cleared cookies and private windows, and the all-zero device ID means no usable device signals. user_hid is "anonymous" for anonymous checks.

• A missing identification means unverified, never clean.

Security

• Keys stay in the environment. The server never logs keys or secrets and never returns them, not even in error messages. Pass keys through the client's env settings, not command-line flags.

• Read-only. No tool changes anything in ShieldLabs. The Management API tool reads the profile only.

• Visitor data is data. User HIDs, landing URLs, referrers and UTM values in identifications come from visitors' browsers. Markdown output renders every API value as inert inline code, invisible and control characters are shown as visible escapes in every format, json responses carry an untrusted_data_note, and the server instructions tell the assistant to treat these strings as data, never as instructions.

• A shared History API budget. The History API allows about 15 requests per second per domain, shared with your own backend, which polls it for new verdicts. This server sends at most 2 History API requests at a time and 5 per second for the whole process (every tool call and every HTTP client) and queues the rest; after a 429 every queued request waits 1 to 5 seconds (Retry-After).

• Encrypted API calls. Base URL overrides must use https, except on loopback addresses.

• HTTP transport: bearer token required on every request (constant-time comparison), requests with an unlisted Origin refused, Host checked on loopback binds, 1 MB body limit, and a health endpoint without data. The default bind address is 127.0.0.1. The server warns at start when SHIELDLABS_MCP_TOKEN has fewer than 32 characters (use openssl rand -hex 32).

• Webhook debugging reports whether a signature matches; it never returns the secret or a signature it computed.

• Network access: the ShieldLabs APIs, plus one request to raw.githubusercontent.com for the setup skill of the pinned shieldlabs-skills release when the integrate_shieldlabs prompt runs on stdio (skip it with --offline; never over HTTP). No telemetry.

• Hosted server (--mode public): a 401 challenge before any JSON-RPC runs, and only ShieldLabs access tokens (slat_...) are accepted; any other credential is refused without being sent anywhere. The ShieldLabs API accepts such a token only on its MCP prefix and only with this server's X-Shield-Gateway signature (HMAC-SHA256 over the time, a fresh nonce, the method, the path and the token hash), so a token copied out of a client is useless elsewhere. One client address can have at most 300 new tokens checked per minute. The only state shared between requests is the list of tokens accepted in the last 60 seconds, keyed by their SHA-256.

Errors and retries

Tool errors come back as MCP tool results with isError: true and a message that names the fix. API calls use the retries of @shieldlabs-ai/node: connection errors, timeouts, 429 and 5xx are retried with backoff; 400, 401, 402, 403 and 404 are not, and a Management API 429 is never retried: after one, shieldlabs_get_domain_profile answers from memory until the 10-minute block ends. History API requests wait in the shared budget described under Security. Cancelling a tool call in the client stops its API requests, including the wait for a new verdict and requests still in the queue.

The wait for a new verdict (shieldlabs_get_identification with wait: true, and shieldlabs_explain_risk_score with a request_id) works on one budget of about 10 seconds:

• It polls at once, then after 250 ms, 500 ms, 1 s, 1.5 s and then every 2 s. The last poll runs when the budget ends. Each poll is one request, without retries.

• A 429, a 5xx, a connection error or a timeout does not end the wait. After a 429 the next poll waits the longest of the scheduled step, 1 second and Retry-After capped at 10 seconds, cut short at the end of the budget. When Retry-After, capped at 10 seconds, is longer than the time left, the tool reports the rate limit at once.

• When the budget ends, the tool reports the error of the last poll if it failed, and "not scored yet" otherwise.

• 400, 401, 403 and 404 end the wait at once: a wrong key or base URL does not heal.

Troubleshooting

Compatibility

• Node.js 20, 22 and 24 (tested in CI).

• Hosted mode: Cloudflare Workers (compatibility date 2026-08-15) or Node.js 20 or later; its Worker tests and deploys need Node.js 22 or later.

• MCP TypeScript SDK 1.x: protocol revisions supported by the SDK, tools with output schemas, resources, resource templates and prompts. Transports: stdio and streamable HTTP.

• History API and Management API as documented at docs.shieldlabs.ai; webhook schema version 2026-06-01.

• Semantic versioning: breaking changes only in a new major version.

Deploy the hosted server

The hosted mode (--mode public) serves many users from one server: every request brings the access token of its user's sign-in, which the ShieldLabs account API checks before the server answers. It runs as a Cloudflare Worker, or in a container with Node.js.

How a token is checked: the server sends GET /mcp/v1/ping to the account API with the token and an X-Shield-Gateway: v1 kid=<key ID> t=<unix seconds> n=<nonce> sig=<signature> header. The signature is the unpadded base64url HMAC-SHA256, with the secret of the gateway key, of v1, the time, the nonce, the method, the path with its query and the lowercase hex SHA-256 of the token, one per line. The account API accepts it for 60 seconds either way and refuses a nonce it has seen, so every request gets 16 fresh random bytes. A 200 lets the request through and is remembered for 60 seconds under the SHA-256 of the token; refusals are never remembered. The shieldlabs_check_connection tool always pings again.

All URLs must use https, except on localhost, 127.0.0.1 and [::1]. The server never logs a token, the gateway secret or a signature: every request writes one JSON line with the route, the JSON-RPC method and tool name, the status, the duration, 8 hex characters of the token hash and how the token was checked.

Cloudflare Workers

wrangler.jsonc holds two environments, each on its custom domain with the variables above and three Rate Limiting bindings: RL_TOKEN (120 requests per minute per token), RL_ANON (60 per minute per address for requests without an accepted token) and RL_TOKEN_CHECK (300 per minute per address for tokens that are not in the cache, counted before the account API is asked). The network 160.79.104.0/21 of Claude's hosted connectors, where many users share addresses, is not limited per address.

Set the gateway key once per environment, then deploy. Always name the environment; the top level of wrangler.jsonc repeats dev, so a deploy without --env never touches production:

npx wrangler secret put MCP_GATEWAY_KEY --env dev
npx wrangler deploy --env dev
npx wrangler deploy --dry-run --env dev   # bundle only, no Cloudflare account needed

To run the Worker on your machine against a local account API, put the overrides in .dev.vars (ignored by git) and start wrangler dev:

cat > .dev.vars <<'EOF'
SHIELDLABS_PUBLIC_ORIGIN=http://localhost:8787
SHIELDLABS_PORTAL_URL=http://localhost:8090
SHIELDLABS_AUTH_ISSUER=http://localhost:8090
MCP_GATEWAY_KEY=k1:replace-with-the-k1-secret-of-your-local-api
EOF
npx wrangler dev --env dev --port 8787

Container

The same handler runs on Node.js with --transport http --mode public, for example with the image:

docker run --rm -p 8787:8787 \
  -e SHIELDLABS_PUBLIC_ORIGIN=https://mcp.example.com \
  -e SHIELDLABS_PORTAL_URL=https://account.shieldlabs.ai \
  -e MCP_GATEWAY_KEY \
  ghcr.io/shieldlabs-ai/shieldlabs-mcp:<version> --transport http --mode public --host 0.0.0.0

It speaks plain HTTP: put a TLS proxy in front of it, and let only that proxy reach the port. Rate limits are kept in memory per process, and request logs go to stdout, one JSON line per request.

The per-address limits use the address of each TCP connection, which behind a proxy is the proxy's for every client. Add --trust-proxy to take the client address from CF-Connecting-IP instead: the proxy must then set that header on every request, replacing any value the client sent. Cloudflare sets it; with nginx, use proxy_set_header CF-Connecting-IP $remote_addr;.

Development

npm ci
# Until @shieldlabs-ai/node is published, build its tarball in a checkout of shieldlabs-node:
(cd ../shieldlabs-node && npm ci && npm pack)
npm install --no-save ../shieldlabs-node/shieldlabs-ai-node-1.0.0.tgz
npm run typecheck
npm run lint
npm test -- --coverage
npm run build
node dist/index.js --help
npm run smoke            # the built server over stdio against the fake History API
npm run test:worker      # the hosted mode in workerd (Node.js 22 or later)
npm run worker:check     # the Worker bundle: no Node.js built-in module, size limit

@shieldlabs-ai/node is bundled into dist/ at build time, so the published package depends only on @modelcontextprotocol/sdk and zod.

Fake History API

scripts/mock-history-api.mjs serves a deterministic dataset (test/mock-data/, generated by scripts/generate-mock-data.mjs) as a fake History API and Management API:

npm run build
node scripts/mock-history-api.mjs --port 8788
# in another terminal: the MCP Inspector CLI passes environment variables with -e
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  -e SHIELDLABS_API_KEY=sec_evaldata-mockdata-00000001 \
  -e SHIELDLABS_API_BASE_URL=http://127.0.0.1:8788 \
  --method tools/list

npm run smoke does the same without extra downloads: it starts the fake API, runs the built server over stdio with the MCP SDK client and calls its tools, resources and prompts.

See CONTRIBUTING.md. Documentation: docs.shieldlabs.ai. Support: contact@shieldlabs.ai.

License

MIT