Impact Boundary Labs
GitHub
Documentation navigation

MCP Boundary

Policy Examples

Policy is how you make MCP tools more specific than "the agent can see this server".

A policy can say:

  • show this tool to the agent
  • hide this tool from the agent
  • allow this tool
  • block this tool before it reaches the MCP server
  • require local human review before execution
  • limit result size
  • require simple argument rules
  • bind a write to previously observed state

Policies use the native downstream tool name in downstream_tool_name. The agent-facing name returned by tools/list is client-safe and may replace dots with underscores. For example, the agent may call email-demo_email_send_email, while the policy still targets native email.send_email.

Do not paste the agent-facing tools/list name into downstream_tool_name unless that is also the downstream server's native tool name.

Start With The Email Demo

The local email demo has four native downstream tools:

email.search_threads
email.get_thread
email.create_draft
email.send_email

A simple policy can allow search/read/draft and block send:

json
{
"version": "mcp-adapter-host-policy/v1",
"servers": [
{
"server_id": "email-demo",
"tools": [
{
"downstream_tool_name": "email.search_threads",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "allow",
"result_limits": {
"max_result_bytes": 32768
}
},
{
"downstream_tool_name": "email.get_thread",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "allow",
"result_limits": {
"max_result_bytes": 32768
}
},
{
"downstream_tool_name": "email.create_draft",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "allow"
},
{
"downstream_tool_name": "email.send_email",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "block"
}
]
}
]
}

This means:

search threads      allowed
read a thread       allowed
create a draft      allowed
send email          blocked before the demo server runs

Visibility

Visibility controls whether the agent can see a tool.

Common values:

visible          the agent can see the tool
dashboard_only   the dashboard can show it, but the agent should not request it
hidden           do not expose it to the agent

Use this when a server has tools that should exist for inspection but should not be part of the agent's normal tool surface.

Allow, Block, And Review

policy_input_mode controls the decision input for a tool.

Common values:

allow            this tool may continue through the checked path
block            stop before downstream execution
review_required  stop before execution and create a pending local approval

For review_required, the first call is not executed. The dashboard can show the pending item and, with the local operator token, approve or reject it. An approval is not execution: the agent must retry with top-level approval_retry metadata before the tool can run.

Argument Rule Example

Argument rules can keep a tool narrow.

Example: allow a customer lookup only for selected customer IDs.

json
{
"downstream_tool_name": "support_db.get_customer_summary",
"exposure": "visible",
"handling_mode": "generic_guarded",
"policy_input_mode": "allow",
"argument_rules": [
{
"field": "customer_id",
"required": true,
"max_chars": 32,
"allowed_values": ["C-1001", "C-1002"]
}
],
"result_limits": {
"max_result_bytes": 16384
}
}

This does not require the downstream MCP server to know about MCP Boundary. The check happens before the tool call reaches the server.

State Binding

State binding is for read-then-write flows.

Example idea:

1. Agent reads a customer record.
2. MCP Boundary records the state facts or token.
3. Agent asks to update that record.
4. The update must match the current state expectation.

This helps avoid blind writes against stale state. It is useful for tools that update, move, delete, send, or otherwise create side effects.

Hidden Effects

MCP Boundary can only check the MCP call that passes through it.

If a downstream MCP server hides a destructive internal effect behind a harmless-looking outer tool, classify the outer tool by the strongest effect it may cause, or split the downstream server into more specific tools.

More Detail

The full policy guide ships inside the downloaded ZIP as docs/mcpboundary/publish/tool_rules/policies.md.