MCP Boundary by Impact Boundary Labs
Documentation navigation

MCP Boundary

Getting Started

This is the short website version. A longer guide ships inside the downloaded ZIP/tarball at docs/mcpboundary/publish/guides/getting-started.md.

The normal first real setup is:

start local dashboard
-> paste existing MCP client config
-> detect and import one server
-> copy Agent Config back into the MCP client
-> restart/reload the MCP client
-> run one safe tool call
-> check Activity
-> tighten policy in Builder after the route works

The local email demo is still useful, but it is a practice flow, not the main path for a real MCP client.

1. Download And Open The Folder

Download the package for your platform and extract it.

Linux tarball:

sh
mkdir mcpboundary
tar -xzf mcpboundary-*.tar.gz -C mcpboundary
cd mcpboundary
./mcpboundary --version

Windows ZIP, from PowerShell in the extracted folder:

powershell
.\mcpboundary.exe --version

The short mcpboundary command works only after MCP Boundary is installed on your PATH. Package-first examples use ./mcpboundary on Linux and .\mcpboundary.exe on Windows.

2. Start The Dashboard

Linux:

sh
./start-dashboard.sh

Windows:

powershell
.\start-dashboard.cmd

Open the dashboard URL printed by the script.

Setup Import, Load tools, and Save policy need the dashboard edit token. On Linux, ./start-dashboard.sh also writes the URL and token to:

dashboard-session.txt

Use that file if your desktop starts the dashboard without showing a useful terminal window. Treat it as local operator state.

3. Import Your Existing MCP Config

Open the MCP config used by your agent and copy the existing mcpServers config.

In the dashboard:

  • Open Setup.
  • Paste the existing config into Import from MCP config.
  • Click Detect servers.
  • Select the server you want to route through MCP Boundary.
  • Paste the dashboard edit token.
  • Click Import selected server.

Import creates a local Boundary setup. MCP Boundary does not edit your MCP client automatically. Import also tries to load the server's tool list for Builder. This discovery step does not start the protected connection used by your agent. If discovery does not complete, use Load tools in Setup after fixing the server or authentication setup.

4. Copy Agent Config

After import, open Agent Config.

Copy the generated Protected config and paste it back into your MCP client config. Replace the original entry for the selected server.

The generated command should use an absolute path to the package-local mcpboundary binary, or bare mcpboundary only when it is installed on PATH. Do not guess the path by hand if the dashboard generated it.

Copy Agent Config before refreshing the dashboard page. The raw pasted MCP client config is kept only in the browser session so the generated config can preserve unrelated servers and client-specific fields.

5. Restart Or Reload The MCP Client

Restart or reload your agent/MCP client so it reads the updated config.

Run one safe tool call first. Then open Activity.

Activity appears only for calls routed through MCP Boundary. If Activity stays empty, your MCP client probably still uses the original direct MCP server entry, or it has not reloaded the updated config.

6. Check Tools And Tighten Policy

Open Builder to see what the selected MCP server exposes and what the agent can see through MCP Boundary.

Tighten policy only after the protected route works.

Policy decides what happens when the agent calls a tool:

  • allowed: the call can run
  • review_required: automatic execution stops and review-required feedback is returned
  • blocked: the call is stopped
  • hidden: the tool is not exposed to the agent

For review_required calls, current builds can show a pending local approval. With the local operator token - the same dashboard edit token printed when the dashboard starts - the dashboard can approve or reject that exact pending item. Approval does not execute the tool. The agent must make a later call with top-level approval_retry metadata and the original arguments. See the concrete retry shape in the FAQ.

Use the normal Builder workflow first: select a tool, change its access or input rules, optionally show the server-validated Policy JSON, then save policy with the dashboard edit token. Identity, limits, state fact checks, and optional state binding (read-before-write) are under Advanced controls. Use Builder: Full Policy JSON only when you already have a complete developer Policy file, not as the first-run editing path.

Optional: Local Email Demo

If you want to practice without a real external MCP server, run the simulated local email demo.

Linux:

sh
./quickstart-email-demo.sh

Windows:

powershell
.\quickstart-email-demo.cmd

You can also run:

sh
./mcpboundary quickstart email

or on Windows:

powershell
.\mcpboundary.exe quickstart email

The demo has no provider account, no credentials, no OAuth, no real inbox, and no real email send. It is a safe practice flow for the dashboard and Builder.

Next

Read:

  • How It Works for the runtime model.
  • MCP Tool Rules for visibility, allow/block, argument rules, and result limits.
  • Tested Servers And Limits for what has actual evidence.
  • Real Gmail Setup for a real Gmail-style downstream-managed OAuth path.