> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blursec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mcp

# AI agents & MCP

`@blursec/mcp` turns the SDK into a [Model Context Protocol](https://modelcontextprotocol.io)
server, so AI agents — Claude, GitHub Copilot, Cursor, your own agent loop —
can query the stealer-log database and triage sessions as **tools**.

It follows the same non-negotiables as the SDK: zero runtime dependencies,
k-anonymity (only a 10-hex-char SHA-256 prefix leaves the machine), and
explicit fail-open signaling.

## When to reach for it

* **Security copilots / SOC chatbots** — "is `ada@example.com`'s password in
  any stealer log?" becomes a tool call instead of a dashboard hunt.
* **Incident-response agents** — paste a suspect session token, get
  `tokenType`, `compromised`, severity, and a recommended action back.
* **CI / staging audits** — let an agent sweep seeded test accounts via
  `blursec_check_hash` without any plaintext secret entering the model
  context.

What it is **not** for: the `/login` hot path. Agents add seconds of latency;
the SDK's 1500 ms credential check belongs in your server code, not behind an
LLM.

## Setup

Install once (or rely on `npx`):

```bash theme={null}
npm i -g @blursec/mcp @blursec/sdk
```

Configuration is environment-only — the API key never appears in argv or
prompt text:

| env var               | purpose                                      |
| --------------------- | -------------------------------------------- |
| `BLURSEC_API_KEY`     | API key (required)                           |
| `BLURSEC_ENVIRONMENT` | `production` (default) / `staging` / `local` |

### Claude Desktop / Claude Code

```json theme={null}
{
  "mcpServers": {
    "blursec": {
      "command": "npx",
      "args": ["-y", "@blursec/mcp"],
      "env": { "BLURSEC_API_KEY": "bsk_live_..." }
    }
  }
}
```

### VS Code (GitHub Copilot agent mode)

`.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "blursec": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@blursec/mcp"],
      "env": { "BLURSEC_API_KEY": "${input:blursec-api-key}" }
    }
  }
}
```

### Any other MCP host

The binary is `blursec-mcp`; it speaks MCP over stdio (newline-delimited
JSON-RPC). Point your host at the command and supply the env vars.

## The tools

| Tool                       | SDK surface                          | Notes                                                                                                                                                                         |
| -------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blursec_check_credential` | `credentials.check(email, password)` | Hashes locally, transmits the 10-char prefix only. Optional `context` (`ip`, `userAgent`, `country`, `userId`, `deviceFingerprint`) feeds Layer-3 risk scoring.               |
| `blursec_check_token`      | `credentials.checkToken(token)`      | Same model for session cookies / bearer tokens.                                                                                                                               |
| `blursec_check_hash`       | `credentials.checkHash(sha256)`      | **Most private** — the agent supplies a 64-char digest, so the raw secret never enters the conversation. For credentials: `SHA-256(lowercase(trim(email)) + ":" + password)`. |
| `blursec_verify_session`   | `sessions.verify(token)`             | Adds `tokenType` (`jwt`/`opaque`) and a `compromised` flag. JWTs are hashed by signature segment only.                                                                        |
| `blursec_whoami`           | `auth.whoami()`                      | Connectivity / key-scope sanity check.                                                                                                                                        |

Every check returns the same structured result the SDK gives application
code: `leaked`, `severity`, `recommendedAction`, `firstSeen`, `sources`,
`failedOpen`. Tool descriptions instruct the model to treat
`failedOpen: true` as *unknown*, never as *safe*.

### What's intentionally missing

`auth.rotate` is not exposed. It revokes the live API key instantly — an
autonomous agent calling it by mistake would disable leak protection for the
whole integration. Rotate keys from your own tooling, with a human in the
loop.

## Example agent session

> **User:** We got a phishing report for [ada@example.com](mailto:ada@example.com). Can you check if
> her current session is compromised? Token: `eyJhbGciOi...`
>
> **Agent:** *(calls `blursec_verify_session`)* The session token matches a
> stealer-log entry first seen 2026-06-08 across 3 sources, severity
> **high**, recommended action **force\_reset**. You should revoke her
> sessions and force a password reset.

## Embedding without stdio

`BlursecMcpServer` is exported for in-process hosting (custom transports,
tests, serverless wrappers):

```ts theme={null}
import { BlursecMcpServer, createBlursecFromEnv } from "@blursec/mcp";

const server = new BlursecMcpServer(createBlursecFromEnv());
const reply = await server.handleLine(jsonRpcLine); // undefined = notification
```

## Where AI does *not* belong

Two of the SDK's invariants double as AI-integration rules:

1. **Never put an LLM on the credential-check hot path.** The 1500 ms
   timeout and fail-open behavior exist because this runs in front of
   `/login`. AI belongs *before* (risk-model-driven `severityActions`) or
   *after* (triage, remediation, reporting) the check.
2. **Never let raw credentials reach a model.** Hash first
   (`hashCredential`, then `blursec_check_hash`) or scrub
   (`scrubPII`) — prompts and traces count as "leaving the process".