# MCP Shield

> MCP Shield checks your MCP server's traffic at the OpenWAF edge: method and tool policy, prompt-injection and credential-leak checks, per-token limits.

MCP Shield is an MCP-aware layer in the OpenWAF edge. You publish your own MCP server (Model Context Protocol, Streamable HTTP transport) behind OpenWAF, declare its path as an **MCP endpoint**, and the edge reads every JSON-RPC message that goes through it: it checks which methods and tools are called, inspects tool arguments and tool results for prompt injection and leaked credentials, and limits requests per token.

It is part of [Bots and AI agents](https://developers.openwaf.dev/ai-crawl-control/) and follows the same switch: off by default, opt-in per endpoint, and it starts in **log mode**, where it only records what it would do.

## Why an MCP server needs its own checks

A model reads what an MCP server returns as context and decides from it which tool to call next. That opens risks an ordinary API firewall does not look at:

| Risk | How it arrives | What MCP Shield does |
|---|---|---|
| Indirect prompt injection | Text written by a third party inside a tool result, a resource, a prompt or a tool description: “ignore previous instructions”, fake `<system>` tags, orders to call another tool without asking the user, exfiltration links | Inspects the strings of every response and replaces the poisoned message with a JSON-RPC error when you choose `block` |
| Unexpected methods or tools | A client, or a manipulated model, calls a tool this endpoint should not expose, such as a destructive one | Method allowlist and tool allow and deny lists |
| Credential leaks | API keys, private keys or database URLs in tool arguments or results | DLP patterns on requests and responses |
| Abusive clients | One token sending hundreds of calls a minute | Requests per minute per token |
| Malformed or oversized messages | Bodies that are not JSON-RPC, or too large | Size cap and JSON-RPC validation |

MCP Shield does not authenticate anyone: your MCP server still checks its tokens. The edge only uses a SHA-256 hash of the `Authorization` header to count requests and to fingerprint events.

## What happens to a request

1. **Endpoint.** The first endpoint of the site's list (AI or MCP) whose path prefix matches the request path and whose HTTP methods include the request method applies.
2. **Rate.** With a per-token limit, the request counts against `sha256(Authorization)` (the client IP when there is no such header).
3. **Size.** The `POST` body is read up to the endpoint's size cap.
4. **JSON-RPC.** The body must be one JSON-RPC 2.0 message or a non-empty batch array.
5. **Policy.** Each client message with a `method` is checked against the allowed methods; `tools/call` names against the tool lists.
6. **Request inspection.** Tool arguments, `resources/read` parameters and prompt arguments.
7. **Your server.** The request is forwarded unchanged, except that `Accept-Encoding` is removed so the response arrives readable.
8. **Response inspection.** JSON responses are checked whole (up to 2 MiB); `text/event-stream` responses are checked event by event as they stream, and each event is forwarded as soon as it is checked.


Session headers (`Mcp-Session-Id`, `MCP-Protocol-Version`, `Last-Event-ID`), SSE event ids, `DELETE` requests, the framing of `GET` streams and `202` answers are never changed.

## Log and enforce

The site's Bots and AI agents mode decides whether the edge acts:

- **Log:** nothing is blocked. Every policy hit and detection becomes an event and a counter, so you can see what enforce would do.
- **Enforce:** the edge answers out-of-policy calls itself and, where inspection is set to `block`, rejects the request or replaces the response.

Blocks use JSON-RPC errors with the id of the blocked request, so your MCP client shows the error for that one call and the session continues. The [errors page](https://developers.openwaf.dev/mcp-shield/errors-and-events/) lists every code.

> **Caution: Pattern matching, not a model**
>
> The detectors are deterministic regular expressions in English and Spanish. They stop known injection and credential shapes; they do not prove a message is safe, and paraphrases or encodings they do not cover get through. See [what is and isn’t detected](https://developers.openwaf.dev/mcp-shield/detection/).


## Our own MCP server

The [OpenWAF MCP server](https://developers.openwaf.dev/mcp/), `mcp.openwaf.dev`, is the first endpoint behind MCP Shield. It runs in log mode first, as recommended here, before any part of it moves to enforce.

## Next steps

- [Enable MCP Shield](https://developers.openwaf.dev/mcp-shield/enable/): put an endpoint behind it from the dashboard, the CLI, the API or your AI assistant.
- [Settings and modes](https://developers.openwaf.dev/mcp-shield/settings/): every setting, its default and how log and enforce combine with inspection.
- [What is and isn’t detected](https://developers.openwaf.dev/mcp-shield/detection/): the inspected text, the detectors and the gaps.
- [Errors and events](https://developers.openwaf.dev/mcp-shield/errors-and-events/): what clients receive and what you see.
- [FAQ](https://developers.openwaf.dev/mcp-shield/faq/): short answers to the usual questions.