Write policy for an MCP server
Policy decides each request the agent makes to an MCP server. Permit the server’s startup or network connection, then permit its MCP calls.
Use a forbid rule to block a tool or a specific argument value.
Audience: an operator who has declared a server in the [mcp.<name>] table and
writes its rules in policy.dw.
Before you start
Section titled “Before you start”- A box from getting started.
- An
[mcp.<name>]table for the server in itsbox.toml.
Step 1. Allow the server
Section titled “Step 1. Allow the server”To allow a stdio server, permit shell:spawn for its program and mcp:call for its name:
@id("fetch_start")permit (principal, action == Box::Action::"shell:spawn", resource)when { context.input.program == "mcp-server-fetch" };
@id("fetch_calls")permit (principal, action == Box::Action::"mcp:call", resource)when { context.input.server == "fetch" };To allow an http server, permit net:connect and http:request for its host, and mcp:call
for its name:
@id("github_connect")permit (principal, action == Box::Action::"net:connect", resource)when { context.input.host == "api.githubcopilot.com" && context.input.port == 443 };
@id("github_request")permit (principal, action == Box::Action::"http:request", resource)when { context.input.host == "api.githubcopilot.com" };
@id("github_calls")permit (principal, action == Box::Action::"mcp:call", resource)when { context.input.server == "github" };The mcp:call permit covers every method and every tool on the server. One permit can name
several servers:
@id("mcp_servers")permit (principal, action == Box::Action::"mcp:call", resource)when { ["fetch", "github"].contains(context.input.server) };| Action | Field | Value |
|---|---|---|
shell:spawn | context.input.program | Element 0 of the server’s command. |
context.input.program_path | The program’s file, with every link resolved. ~ is the operator’s home. | |
context.input.arg1, arg2, arg_count | The server’s arguments. | |
context.input.command | By default, the server’s full command as written in box.toml: the program and its arguments, joined by spaces. Use it with like to match an argument past the second. An argument that holds ${OTEL_EXPORTER_OTLP_*} is the name here, and the value the box puts in its place in arg1 and arg2. | |
mcp:call | context.input.server | The [mcp.<name>] table’s name. |
context.input.method | The MCP method, such as tools/list or tools/call. For the harness’s reply to a stdio server’s own request, the method of that request, such as roots/list. | |
context.input.tool | The tool name, on tools/call. |
For an enabled wildcard command, command instead holds the effective
launch command, with received values in the * positions and fixed arguments expanded.
arg1, arg2, and arg_count describe those same launch arguments.
A permit that checks only program, as above, matches every value supplied in the * positions.
To restrict those values, add conditions on the effective arguments.
Step 2. Connect the harness
Section titled “Step 2. Connect the harness”Add each server to the harness’s own MCP configuration.
- A
stdioserver: set its command to the server’s fullcommandfrombox.toml: the program, then every argument, in the same order. The harness runs the alias with those arguments, and the box starts the server whosecommandmatches. Withargument_wildcards = trueon that server, supply the runtime value for each*position. - An
httpserver: set its URL. For a server withsecret.ref = "env://NAME", send the placeholder fromNAMEin the header, or setsecret.inject = "always"and send no header.
Use your client’s configuration format for these settings. For this box.toml table:
[mcp.playwright]type = "stdio"command = ["npx", "-y", "@playwright/mcp"]a client that takes a command and its arguments apart gets:
{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] } } }A harness entry that sets only the program, "command": "npx" with no args, is refused for this
server with no MCP server declares "npx"; servers on npx: playwright. Add the
arguments to the harness entry. The same applies to every stdio server whose command has
arguments.
The server URL must match the server declared in box.toml.
Step 3. Find the tool and argument names
Section titled “Step 3. Find the tool and argument names”A per-tool rule names a tool as <server>::Action::"<tool>", and reads that tool’s arguments as
context.input.<argument>. The namespace is the server name with each character other than a
letter, a digit, or _ changed to _, so my-server becomes my_server.
policy generate-schema starts each declared server, reads its tools/list, and writes the
per-tool actions and their argument types:
./box-core/box policy generate-schema --config my-box/box.toml --output-dir /tmp/schema/tmp/schema/actions.cedarschema holds one namespace per server, one action per tool, and the
arguments of each tool. A JSON integer or number is a Long, and an enum is its base type.
Step 4. Narrow the server
Section titled “Step 4. Narrow the server”Each rule below sits beside the server’s mcp:call permit.
| Goal | Rule |
|---|---|
| Block one tool | forbid (principal, action == github::Action::"get_me", resource); |
| Block one argument value | forbid (principal, action == github::Action::"search_repositories", resource) when { context.input has perPage && context.input.perPage > 5 }; |
| Allow one argument value only | forbid (principal, action == my_server::Action::"query", resource) when { !(context.input has mode && context.input.mode == "read") }; |
| Hide a server’s tools | forbid (principal, action == Box::Action::"mcp:call", resource) when { context.input.server == "deepwiki" && context.input.method == "tools/list" }; |
To allow only some tools, name them in the server’s mcp:call permit:
@id("github_calls")permit (principal, action == Box::Action::"mcp:call", resource)when { context.input.server == "github" && (context.input.method != "tools/call" || (context.input has tool && ["search_repositories", "get_file_contents"].contains(context.input.tool)))};A per-tool rule works the same for a stdio server and an http server.
- Narrow a tool with a per-tool
forbid, or with the tool list in themcp:callpermit. A per-toolpermitleaves the verdict as themcp:callpermit set it. - Test an optional argument with
hasbefore you compare it. A rule that allows one value only, like the third row above, also refuses a call that omits the argument. - A tool name and an argument name match the server’s
tools/listspelling exactly.
Step 5. Cap how often the agent calls a server
Section titled “Step 5. Cap how often the agent calls a server”A forbid with a when temporal clause caps calls. This rule refuses a third tools/call to
github within five minutes:
@id("cap_github_calls")forbid (principal, action == Box::Action::"mcp:call", resource)when { context.input.server == "github" && context.input.method == "tools/call" }when temporal { exists (n: Long). ( (count for (t: Timepoint). where ( formerly within 300s ( Box::Action::"mcp:call"::request{ input.server: "github", input.method: "tools/call" } && tp(t) ) )) == n && n >= 2 )};::request counts every attempt, including a refused one. ::response counts calls that reached
the server.
Result
Section titled “Result”Restart the box. The decision log records each decision with the rule’s @id. A call the server
permit allows names that permit, such as github_calls. A call a per-tool forbid refuses names
that forbid and the per-tool action. The agent gets each refusal as an MCP error.
Troubleshooting
Section titled “Troubleshooting”| Error message (excerpt) or symptom | What to do |
|---|---|
MCP server "<name>" may not start | No shell:spawn permit for the program. |
no MCP server declares "<command>" | The harness command or arguments do not match a declared server. Copy its command from box.toml, as in step 2. With argument_wildcards = true, supply a value for each * argument. |
Two MCP tables declare overlapping wildcard commands | The wildcard entries can match the same request, so Box refuses to start. Give them fixed arguments that distinguish them. An exact entry may overlap a wildcard entry; the exact entry takes priority. |
MCP command matches multiple servers | No exact entry matched, and more than one wildcard entry matched the received command. The launch is refused. |
| The harness shows the server with zero tools | A rule refuses tools/list for the server. |
the MCP tool catalog is not accepted | The agent called a tool before the server’s tools/list succeeded. |
the tool is not in the accepted MCP catalog | The server’s tools/list does not name the tool, spelled exactly. |
A refusal that says [default-deny] | No mcp:call permit names the server. |
A refusal that says [default-deny], and the startup warning a per-tool rule never loaded printed | Box cannot enforce a per-tool rule and refuses the calls it can identify. See When a rule cannot load for causes and fixes. |
A refusal that names an @id | That forbid matched, on mcp:call or on the per-tool action. |
Resource address errors
A URI (Uniform Resource Identifier) is a resource address, such as file:///tmp/report.txt.
These errors concern the address in a resources/read request.
The messages use hier-part for the part after file: or https: and before a query (?) or fragment (#).
For example, in https://notes/page?format=text, the hier-part is //notes/page.
The authority contains the host, an optional port, and any login information before @.
For example, in https://notes:443/page, the authority is notes:443.
| Error message (excerpt) | What to do |
|---|---|
a file URI that carries a query is refused | The file address includes a non-empty query, such as ?format=text. Remove the query. |
a resource URI that holds a space, a control character, or a backslash is refused | The address contains a space, control character, or backslash. Encode spaces in paths or queries as %20. Remove control characters. Use / for path separators. |
a resource URI whose hier-part is neither an absolute path nor an authority is refused | The address is missing a leading slash or // before its host. Use file:///etc/passwd instead of file:etc/passwd, or https://notes/page instead of https:notes/page. |
an http or https URI with no authority is refused | The web address has no host. Use https://host/path instead of https:///path. |
a resource URI whose authority is not RFC 3986 is refused | The host or port has an invalid format. Put IPv6 addresses in brackets. Use digits for the port and the ASCII xn-- form for international domain names. |
an http or https URI that carries userinfo is refused | The web address contains login information before the host, such as user@. Remove that information from the address. |
a file URI whose path holds an encoded slash is refused | The file path contains %2F, an encoded slash. Use / between path components. HTTP and HTTPS resource addresses can retain %2F. |
a resource URI whose host holds a percent-escape of a reserved or non-ASCII octet is refused | The host contains unsupported percent-encoded characters. Write the host name directly. For international domain names, use the ASCII xn-- form. |
When a rule cannot load
Section titled “When a rule cannot load”When a per-tool rule cannot load, Box starts without that rule.
If Box identifies the calls the rule covers, it refuses them with [default-deny].
Otherwise, those calls can still pass under the server’s mcp:call permit.
Check which rules Box can refuse for before relying on the policy.
The startup warning is a per-tool rule never loaded for ["<server>"]. Check these causes:
| Cause | Fix |
|---|---|
A rule refuses tools/list, so Box cannot discover the server’s tools. | Permit tools/list for that server. |
| The server’s catalog does not offer the named tool. | Correct the tool name, or update the rule if the server removed the tool. |
| The rule reads an argument with a different name or compares it against the wrong type. | Match the argument name and type in the server’s catalog. |
Removing the per-tool rule also clears the warning, but removes its restriction.
The warning names every server the rule was waiting for, so when a rule reads one server’s tool from history it names that server too, even when that server is answering correctly.
Which rules Box can refuse for
Section titled “Which rules Box can refuse for”Box works out which calls an inert rule would have decided in two ways: from the tool the rule names
in its head, and from a when condition that pins context.input.server and context.input.tool
to one quoted name each. Those two rules fail closed: their calls get refused.
A pin still counts when other tests sit beside it, as in context.input.server == "svc" && context.input.tool == "approve" && context.input.method != "tools/list", because each test joined
by && has to hold. A pin does not count when it sits inside a ||, a negation, or an if, or in
an unless condition, because there the rule may reach some other tool instead.
Every other rule fails open: its calls run on the mcp:call permit while the rule enforces
nothing. These are the shapes, and each is worth checking your own policy against:
An inert rule on mcp:call whose condition … | Why Box holds nothing |
|---|---|
| pins the server alone | Every tool on that server is in reach, and the rule names none of them. |
picks tools with ["approve", "reject"].contains(context.input.tool) | A set membership is not an equality, so neither name is a pin. |
matches with context.input.tool like "appro*" | A pattern is not an equality. |
offers a choice, as in context.input.server == "svc" && (context.input.tool == "a" || context.input.tool == "b") | The server pin counts, because it still has to hold; the two tool names do not, because only one of them need hold. One pin alone names no tool. |
narrows on context.input.method, or on an argument | Those reach tools the rule never names. |
| does not narrow at all | Every tool call is in reach. |
Read the startup warning as the signal that a rule went inert, then check it against the table
above to learn whether its calls are being refused or allowed. To get the refusal, name the tool in
the rule’s head, or pin the server and the tool to one name each in a when condition.
Write one rule per tool where you need several.
See also
Section titled “See also”- The
[mcp.<name>]table: the keys for astdioand anhttpserver. - MCP servers in the design guide: how the box starts a server and decides each call.
- Policy in the design guide: how the engine decides, and what refuses to load.