MCP Tool Rules Reference

The easiest mental model:

Start transparent.
Keep useful tools working.
Harden the tools that can cause damage or leak too much data.

MCP Boundary should not make a server useless by default. The purpose is to add a boundary, visibility, and selective hardening, not to force you to rebuild every server by hand.

For practical rule patterns and server-specific playbooks, read MCP Tool Rule Library after this reference.

What A Rule Config Looks Like

A rule config is a JSON policy file. The public docs call these MCP Tool Rules, but the JSON schema still uses the existing policy field names.

This is the complete rule config used by the local email demo:

This file says:

• use policy schema mcp-adapter-host-policy/v1
• apply these rules to server email-demo
• expose search, read, and draft tools
• allow those tools to proceed to the normal Core path
• expose send, but block it before downstream execution

The Fields You Usually Edit

For a first rule config, you mostly edit these fields:

Do not invent tool names. Use the exact names from the dashboard or from tools/list.

How To Create Your First Rule Config

• Add your server.
• Run discovery or open the dashboard.
• Go to Tools.
• Copy exact tool names from the tool list.
• Start with one or two obvious rules.
• Validate the JSON in the dashboard Policy page.
• Save or place the rule config where your profile references it.
• Restart the runtime with that profile.
• Trigger one harmless call from your agent.
• Check Activity.

The dashboard may generate a draft rule config for selected tools. A draft is not active just because it appears in the dashboard. It becomes active only when saved and used by the runtime profile.

Tool Visibility

Visibility controls whether the agent can see a tool.

Common choices:

• visible: the agent can see the tool
• dashboard_only: the dashboard can show the tool, but the agent does not get it
• hidden: the tool is hidden from normal use
• unsupported: MCP Boundary has discovered the tool, but the current runtime cannot safely handle it

Use dashboard-only or hidden for tools that should not be offered to the agent at all.

Basic: Requestability

Requestability controls whether a visible tool can be requested.

A visible tool is not automatically executed. It still goes through the checked runtime path:

requestability -> decision -> downstream execution -> activity/outcome

Transparent mode may mirror discovered tools as requestable by default. That is a usability default, not a Core bypass.

Call Rules

A call rule describes what should happen when the agent requests a tool.

Common outcomes:

• allow: the call may proceed to the checked decision path
• block: the call is stopped before downstream execution
• review_required: the call is not treated as normal allowed work

Important: the current release does not provide a dashboard approval queue. If you need a human approval workflow, treat that as future work, not as an existing button in this release.

Simple Email Example

A practical email-style policy might classify tools like this:

email.search_threads    visible + allow
email.get_thread        visible + allow
email.create_draft      visible + allow
email.send_email        visible + block
email.trash_message     dashboard_only + block

This means:

• the agent can search and read
• the agent can create drafts
• direct sending is stopped
• trash/delete tools are not offered as normal agent tools

This is only an example. Real provider servers have their own exact tool names.

Result Limit Example

Use result_limits when a tool can return too much text:

This does not decide whether the tool is safe. It only bounds the result size.

Advanced: Argument Rules

Argument rules let you restrict inputs.

Examples:

• only allow customer_id values from a test list
• block external recipients
• block bcc
• require a specific state_id
• limit a search query length
• require dry_run=true for risky tools

Use argument rules when blocking the whole tool would be too blunt.

Example:

This means:

• customer_id must exist
• it must be short
• only two customer IDs are allowed
• downstream is not called if the argument rule fails

Argument rules apply only to top-level fields. They do not use nested paths such as customer.id.

Result Limits

Result limits control how much data can come back.

Useful limits:

• maximum output size
• maximum number of items
• maximum text length per field
• truncation with clear reason

Result limits are important for large MCP servers. A tool can be useful and still produce too much data for an agent context.

State Binding

State binding means the tool call must match an expected state.

Example:

Update customer C-1002 only if the current state hash still matches what was inspected.

Why this matters:

• the agent may inspect data
• time passes
• the underlying data changes
• a write based on stale state may be wrong

State binding is a way to say:

Do not execute this write if the world changed since the read.

This is more advanced than a first-run setup, but it is useful for database, ticketing, workflow, and mailbox actions.

A state-bound pattern usually has two parts.

First, a read tool records a bounded observation:

Then a write tool requires a reference to that observation:

In plain language:

• the agent first reads customer state
• MCP Boundary records selected facts for a short time
• the later write must refer to that observed state
• if the state reference does not match, the write is not treated as normal allowed work

This is useful when a write depends on what the agent previously saw.

Review Required

review_required is a policy state for work that should not silently proceed as normal allowed work.

Current limitation:

• the dashboard does not yet provide approve / reject / run-anyway buttons
• the agent should receive a clear result that the call requires review
• downstream should not run just because the tool exists

Future versions may add a proper approval workflow. Do not assume it exists in this release.

What Policies Should Not Do

A policy should not pretend to know that a tool is safe just because:

• the tool name contains read
• the tool description sounds harmless
• the provider is popular
• the server was tested once

Tools can be misleading. Use evidence and explicit rules.

Recommended First Policy

For a new server:

• Start transparent so the server is still usable.
• Open Tools and inspect the surface.
• Copy exact tool names.
• Identify obvious destructive tools.
• Hide or block those first.
• Add result limits for broad list/search tools.
• Add argument rules for sensitive fields.
• Run one harmless tool call.
• Check Activity.
• Tighten from evidence, not guesses.

That gives you a usable starting point without turning the first setup into a long security project.

Quick Reference

Common starting choices: