Skip to content

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.

  • A box from getting started.
  • An [mcp.<name>] table for the server in its box.toml.

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) };
ActionFieldValue
shell:spawncontext.input.programElement 0 of the server’s command.
context.input.program_pathThe program’s file, with every link resolved. ~ is the operator’s home.
context.input.arg1, arg2, arg_countThe server’s arguments.
context.input.commandBy 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:callcontext.input.serverThe [mcp.<name>] table’s name.
context.input.methodThe 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.toolThe 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.

Add each server to the harness’s own MCP configuration.

  • A stdio server: set its command to the server’s full command from box.toml: the program, then every argument, in the same order. The harness runs the alias with those arguments, and the box starts the server whose command matches. With argument_wildcards = true on that server, supply the runtime value for each * position.
  • An http server: set its URL. For a server with secret.ref = "env://NAME", send the placeholder from NAME in the header, or set secret.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.

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:

Terminal window
./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.

Each rule below sits beside the server’s mcp:call permit.

GoalRule
Block one toolforbid (principal, action == github::Action::"get_me", resource);
Block one argument valueforbid (principal, action == github::Action::"search_repositories", resource) when { context.input has perPage && context.input.perPage > 5 };
Allow one argument value onlyforbid (principal, action == my_server::Action::"query", resource) when { !(context.input has mode && context.input.mode == "read") };
Hide a server’s toolsforbid (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 the mcp:call permit. A per-tool permit leaves the verdict as the mcp:call permit set it.
  • Test an optional argument with has before 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/list spelling 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.

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.

Error message (excerpt) or symptomWhat to do
MCP server "<name>" may not startNo 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 commandsThe 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 serversNo exact entry matched, and more than one wildcard entry matched the received command. The launch is refused.
The harness shows the server with zero toolsA rule refuses tools/list for the server.
the MCP tool catalog is not acceptedThe agent called a tool before the server’s tools/list succeeded.
the tool is not in the accepted MCP catalogThe 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 printedBox 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 @idThat 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 refusedThe 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 refusedThe 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 refusedThe 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 refusedThe web address has no host. Use https://host/path instead of https:///path.
a resource URI whose authority is not RFC 3986 is refusedThe 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 refusedThe 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 refusedThe 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 refusedThe host contains unsupported percent-encoded characters. Write the host name directly. For international domain names, use the ASCII xn-- form.

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:

CauseFix
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.

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 aloneEvery 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 argumentThose reach tools the rule never names.
does not narrow at allEvery 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.