MCP Boundary by Impact Boundary Labs
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
  • limit result size
  • require simple argument rules
  • bind a write to previously observed state

Use exact tool names discovered from your MCP server. Do not invent aliases.

Start With The Email Demo

The local email demo has four 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 And Block

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  mark as requiring manual review; no dashboard approval queue yet

Important: current MCP Boundary does not have a human approval queue. Treat review_required as a "not executed until handled manually" state for now, not as a clickable approve button.

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 lives in:

  • docs/publish/policies.md