MCP Boundary by Impact Boundary Labs
Documentation navigation

MCP Boundary

How It Works

MCP Boundary does not replace your MCP servers.

For each server you choose, it starts the MCP server you already wanted to use, then puts a local check layer in front of that server's tool calls.

The Normal Setup

Without MCP Boundary, your agent talks directly to MCP servers:

  Agent ──▶ MCP server A
  Agent ──▶ MCP server B

With MCP Boundary, each call passes a local check first. You keep one profile per server, so tools are never merged into one shared list:

  Agent ──▶ [ MCP Boundary · profile A ] ──▶ MCP server A
  Agent ──▶ [ MCP Boundary · profile B ] ──▶ MCP server B

That gives MCP Boundary a chance to check the concrete tool call before it reaches the server.

One Profile Per MCP Server

If you use several MCP servers, you normally create one profile per server.

Example:

gmail profile
github profile
postgres profile

Your agent then gets separate MCP entries:

gmail    -> mcpboundary serve gmail
github   -> mcpboundary serve github
postgres -> mcpboundary serve postgres

The tools are not merged into one giant shared tool list. Each server remains a separate entry for the agent.

The dashboard can show saved profiles and setup state, but choosing a profile in the dashboard does not secretly switch a running agent session.

There are two useful dashboard modes:

  • a runtime dashboard started by quickstart or an active serve <profile> process, connected to one running Boundary profile
  • a workspace dashboard started by ./mcpboundary dashboard, useful for setup, import, Load tools, and Agent Config generation

This distinction matters when Activity is empty or a saved setup change does not affect your agent. Use the workspace dashboard to configure saved setups, then restart or reload the agent and use the runtime dashboard to inspect calls from the running profile.

The workspace dashboard can load tools for a selected saved setup and store a saved tool snapshot for Overview and Builder. Load tools does not execute tools and does not create Activity rows.

What Happens For A Tool Call

For a real tools/call, the path is:

1. Agent asks to call a tool.
2. MCP Boundary checks whether that tool is visible and requestable.
3. The policy input is sent into the decision path.
4. If the call is admitted, MCP Boundary forwards it to the MCP server.
5. If review is required, the call is not forwarded and a pending local approval is created.
6. The result or review state is returned to the agent.
7. The outcome is recorded for the dashboard.

Blocked calls should stop before the downstream MCP server runs.

If a downstream call may have happened but the final result is unclear, MCP Boundary should report that honestly instead of pretending the action succeeded.

Transparent First, Then Harden

The intended first-run behavior is low friction:

Add profiles for the MCP servers you want to protect.
See each server's tools.
Keep normal workflow.
Harden the risky parts.

That does not mean direct passthrough. Calls still go through the Boundary path. It means users should not have to manually allow every single tool before the server becomes usable.

What The Dashboard Does

The dashboard helps you see:

  • setup state
  • profiles
  • discovered tools
  • policy
  • Agent Config for your MCP client
  • activity
  • blocked and failed calls
  • pending local approvals
  • known limitations

The dashboard is not a tool runner or remote approval service. When local human approval is configured, it can show pending items and record approve or reject status with the operator token. It does not retry, force-run, resume, or secretly execute tool calls. Approved work requires a later agent call with top-level approval_retry metadata. See the concrete retry shape in the FAQ.

Credentials And Auth

Different MCP servers handle credentials differently.

Common patterns:

  • no auth: local demo or local utility server
  • env token: the downstream MCP server reads an environment variable
  • downstream-managed OAuth: the downstream server owns browser login and local token files
  • Boundary credential profile: a narrower path for servers designed to use MCP Boundary credential storage

For many email and workspace MCP servers, the practical model is:

Provider login belongs to the downstream MCP server.
Tool execution boundary belongs to MCP Boundary.

MCP Boundary should not expose provider tokens to the agent-facing MCP config.

On Linux, Boundary credential-store/login depends on an OS keyring backend such as Secret Service. Minimal or headless environments may return the bounded status credential_store_unavailable.