# Settings and modes

> Every MCP endpoint setting with its default and limits, and how log and enforce combine with off, log and block inspection.

An MCP endpoint is an entry of the domain's (or a name's) AI endpoints, `ai_agents.endpoints`, with `"kind": "mcp"` and an `mcp` object. A site has up to 20 endpoints counting AI and MCP ones, and each path prefix can be used only once.

```json
{"kind": "mcp", "path_prefix": "/mcp", "methods": ["POST", "GET", "DELETE"],
 "mcp": {"methods_allowed": ["initialize", "ping", "notifications/*", "tools/list", "tools/call"],
         "tools_allowed": [], "tools_denied": ["delete_record"],
         "max_request_kb": 256, "inspect_requests": "log", "inspect_responses": "log",
         "rate_per_token": 120}}
```

## Every setting

| Setting | What it does | Default |
|---|---|---|
| `kind` | `mcp` for an MCP endpoint | — |
| `path_prefix` | Path of your MCP server, starting with `/`, up to 256 bytes | — |
| `methods` | HTTP methods the endpoint covers: any of `POST`, `GET` and `DELETE`, always including `POST` | `POST`, `GET`, `DELETE` |
| `mcp.methods_allowed` | 1 to 64 JSON-RPC methods: exact names, or a prefix ending in `/*` such as `notifications/*` | The twelve standard methods below |
| `mcp.tools_allowed` | Up to 200 tool names. Empty means any tool that is not denied | `[]` |
| `mcp.tools_denied` | Up to 200 tool names that are always refused | `[]` |
| `mcp.max_request_kb` | Largest `POST` body, 1 to 1024 KiB | `256` |
| `mcp.inspect_requests` | `off`, `log` or `block` for tool arguments, `resources/read` parameters and prompt arguments | `log` |
| `mcp.inspect_responses` | `off`, `log` or `block` for tool results, resource contents and everything else the server returns | `log` |
| `mcp.rate_per_token` | Requests per minute per token, 0 to 100000. `0` means no limit | `0` |

The twelve default methods are `initialize`, `ping`, `notifications/*`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `resources/templates/list`, `prompts/list`, `prompts/get`, `completion/complete` and `logging/setLevel`. The dashboard can reset the list to them.

Tool names can use letters, digits and `_ . : / -`, up to 128 characters, and they match the `name` of `tools/call` exactly.

The fields of classic AI endpoints (`max_body_bytes`, `rpm_per_ip`, `rpm_per_session`, `session_header`, `session_cookie`, `injection_action`, `limit_action`) are not used by MCP endpoints and must stay empty.

## Modes

Two switches decide what happens. The site's Bots and AI agents **mode** says whether the edge acts at all; each **inspection** setting says what to do with a detection:

| | Mode log | Mode enforce |
|---|---|---|
| Method or tool outside the policy, rate, size, invalid JSON-RPC | Event, the request passes | The edge answers with an error |
| Inspection `off` | Not inspected | Not inspected |
| Inspection `log` | Event, passes | Event, passes |
| Inspection `block` | Event, passes | Request refused, or response replaced by an error |

So a site in log mode never blocks, whatever the inspection settings say. That makes it safe to set the policy you want first and read what it would do.

## Per-token rate

The limit counts requests per minute keyed by a SHA-256 hash of the `Authorization` header, or by the client IP when there is none. Each edge node counts on its own: with N nodes serving the site, one token can reach up to N times the limit. Set it as a ceiling against runaway agents, not as an exact quota.

## Examples

Read-only tools only (any other `tools/call` is refused):

```json
{"tools_allowed": ["list_zones", "get_zone", "list_records"], "tools_denied": []}
```

Everything except two destructive tools:

```json
{"tools_allowed": [], "tools_denied": ["delete_zone", "delete_record"]}
```

A server that only offers tools (no resources or prompts):

```json
{"methods_allowed": ["initialize", "ping", "notifications/*", "tools/list", "tools/call"]}
```

## Whole domain or one name

The endpoint can live in the domain's settings or in a name's own copy (`--host` in the CLI, the scope selector in the dashboard). A name's Bots and AI agents settings replace the domain's for that name. The endpoint list is always replaced as a whole when you change it.

## Which edge nodes apply it

MCP Shield runs on the OpenWAF edge nodes. A node that does not support it yet still serves the site, without its MCP endpoints, and publishing the change returns a warning that names the node.