# Enable MCP Shield

> Protect an MCP endpoint in log mode from the dashboard, the CLI, the API or your AI assistant, read what it would block, then move to enforce.

This page puts an MCP endpoint behind MCP Shield in log mode, shows where to read what it records, and lists what to check before switching to enforce.

## Before you start

- The domain is active on OpenWAF and the name that serves your MCP server (for example `mcp.example.com`) is proxied.
- Your MCP server speaks Streamable HTTP: JSON-RPC over `POST`, and optionally `GET` for the server's SSE stream and `DELETE` to end a session.
- You have a token or a dashboard account with the `tech` role or higher.
- Bots and AI agents is turned on for the domain or the name. It starts in log mode, which is what you want for now.

An MCP endpoint needs only two values: the **path prefix** of your server (for example `/mcp`) and the type `mcp`. Everything else gets a default: the twelve standard MCP methods allowed, every tool allowed, a 256 KiB request cap, request and response inspection in `log`, and no per-token limit. The [settings page](https://developers.openwaf.dev/mcp-shield/settings/) lists each one.

## Add the endpoint

**Dashboard**

1. Open the domain and go to **AI Crawl Control → MCP Shield**.
2. Choose the scope: **Whole domain**, or the name that serves your MCP server.
3. Add an MCP endpoint: its path prefix, the HTTP methods (`POST`, `GET`, `DELETE`), and, if you want to change them, the allowed JSON-RPC methods, allowed and denied tools, request size, inspection of requests and responses (`off`, `log` or `block`) and requests per minute per token.
4. Save with a reason. The change is a new version of the domain, like any other setting.


The same screen shows the counters per endpoint and per tool, the event kinds, the top detections, recent MCP events and the live **MCP Shield** security events.
**CLI**

```sh
openwaf-cloud ctl zones set example.com --host mcp.example.com \
  ai_agents.enabled=true --reason "Bots and AI agents, log mode"
openwaf-cloud ctl zones set example.com --host mcp.example.com \
  ai_agents.endpoints:='[{"kind":"mcp","path_prefix":"/mcp"}]' --reason "MCP Shield in log mode"
```

`ai_agents.endpoints` is a list and is replaced as a whole: include the AI endpoints the name already has, or they are removed. Without `--host`, the endpoint applies to the whole domain.
**API**

The same change is a JSON merge patch of the domain's edge settings, with a change reason:

```sh
curl -X PATCH "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/edge" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" -H "X-Change-Reason: MCP Shield in log mode" \
  -H "Content-Type: application/json" \
  -d '{"ai_agents": {"enabled": true, "endpoints": [{"kind": "mcp", "path_prefix": "/mcp"}]}}'
```

Invalid settings are refused with a `400` error and nothing changes.
**MCP**

With the [OpenWAF MCP server](https://developers.openwaf.dev/mcp/connect/) connected, ask your assistant to protect the MCP endpoint. It uses the `ai_agents_settings` tool with a patch like the API one: first a simulation with the diff, then the change once you approve it.


## Watch it in log mode

Send real traffic through the endpoint (`initialize`, `tools/list`, the tools your clients use) for a few days, then read the report:

```sh
openwaf-cloud ctl ai mcp example.com --range 7d
openwaf-cloud ctl ai report example.com --view events --kind mcp_blocked_tool,mcp_injection_response,mcp_dlp
```

The report gives, per endpoint, the requests, the JSON-RPC messages, how many would have been blocked, how many had a detection and how many responses passed uninspected; per tool, its calls, blocks and detections; and the detections by id. From your assistant, the `ai_agents_report` tool has the same `mcp` view. Each event carries the method, the tool, the detector ids and a token fingerprint, never the token.

## Move to enforce

1. **Fit the policy to real use.** Remove from the allowed methods what your server does not implement, deny the tools this endpoint should not offer (or list the only ones it should), and set a per-token limit above your legitimate peak.
2. **Check the Bots and AI agents policy.** In enforce mode it applies to requests to the MCP endpoint before MCP Shield does. MCP clients built on Node.js or Python SDKs usually count as `unverified_automation`, and the templates **Verified only** and **Block all unverified automation** would challenge or block them.
3. **Switch the mode to enforce.** Method, tool, size and rate policy are now applied. Inspection set to `log` keeps only recording.
4. **Set inspection to `block` only after reviewing its events.** A tool result that legitimately quotes attack text, such as a security log or documentation, would be replaced by an error. Keeping response inspection in `log` and treating its events as alerts is a valid choice.