Run Mcp

A smart proxy, interactive REPL, and live test harness for Model Context Protocol (MCP) servers.

run-mcp provides three interfaces for interacting with MCP servers:

1. Agent MCP Server (run-mcp) — An MCP server that exposes tools (connect_to_mcp, call_mcp_tool) so AI agents can dynamically connect to and test local MCP projects without hardcoding them in configuration files. This is the default mode when you run npx -y run-mcp.
2. Interactive REPL (run-mcp -- node server.js) — A human-friendly CLI for developers to manually test and explore MCP servers using short, memorable commands (tools/call, status, etc.).
3. Headless CLI (run-mcp call, run-mcp list-tools, etc.) — Single-shot subcommands that output clean JSON to stdout for CI/CD pipelines, shell scripts, and jq workflows.

Interception Rules (Agent Server & REPL)

To protect the CLI and parent agents from large payloads, run-mcp automatically applies the following rules:

• Saving images to disk instead of passing multi-MB base64 strings through
• Enforcing timeouts so a hung tool call doesn't block forever
• Spilling huge text to disk: oversized responses are saved in full, and the truncated reply carries a result id — page through the rest with the read_result tool (or just open the file)

For humans, the REPL mode provides a quick way to test any MCP server without writing client code.

Installation

npm install
npm run build

To install globally (makes run-mcp available system-wide):

npm install -g .

Quick Start

REPL Mode — Test an MCP server interactively

# Start a REPL session with any MCP server
run-mcp -- node path/to/my-mcp-server.js

# Or use npx without installing globally
npx . -- node path/to/my-mcp-server.js

# Or start it without arguments to run the Agent Server mode!
run-mcp

You'll see an interactive prompt:

⟳ Connecting to target MCP server...
  Command: node path/to/my-mcp-server.js
✓ Connected (PID: 12345)
  5 tool(s) available. Type help for commands.

>

Usage

run-mcp [options] [target_command...]

Option	Description
-V, --version	output the version number
-o, --out-dir <path>	Directory to save intercepted images and audio
-t, --timeout <ms>	Default tool call timeout in milliseconds (default: 300000) (Agent Mode only)
--max-text <chars>	Max text response length before truncation (default: 50000) (Agent Mode only)
-m, --media-threshold <kb>	Media size threshold in KB to save to disk (0 to always save, -1 to keep inline)
--mcp	Force start Agent Server mode even if run interactively without arguments
-s, --script <file>	Read commands from a file instead of stdin (REPL Mode only)
--color <mode>	Color output mode: always, never, auto (default: auto)
--open-media	Automatically open intercepted images and audio files using the host OS viewer
--sandbox <mode>	Sandbox execution mode: auto, docker, native, audit, none (default: "none")
--scan	Scan the current workspace and parent directories for any JSON files containing mcpServers
--no-scan-tools	Disable tool-poisoning scanning of tools/list metadata (Agent Mode; on by default)
--redact-secrets	Redact detected secrets/API keys from tool/resource/prompt output (Agent Mode)
--redact-emails	When redacting, also redact email addresses (Agent Mode)
--audit-log <file>	Append a JSONL audit trail of every MCP request/response to this file (Agent Mode)
--transport <mode>	Transport for http(s) targets: auto (default), http (Streamable HTTP), sse
--compress-output	Minify verbose output text to save tokens (lossless JSON minify by default) (Agent Mode)
--compress-aggressive	With --compress-output, also collapse blank lines / trailing whitespace (lossy) (Agent Mode)
-w, --watch	Watch the current directory for file changes and auto-reconnect (REPL Mode only)
--allow-read <paths...>	Paths to allow reading under the sandbox
--allow-write <paths...>	Paths to allow writing under the sandbox
--allow-net <domains...>	Network domains to allow connecting to under the sandbox
--deny-read <paths...>	Paths to deny reading under the sandbox
--deny-write <paths...>	Paths to deny writing under the sandbox
--deny-net <domains...>	Network domains to deny connecting to under the sandbox
-h, --help	display help for command

Examples: $ run-mcp # Test harness (agent mode) $ run-mcp -- node my-server.js # Interactive testing (human REPL mode) $ run-mcp -s test.txt -- node my-server.js # Run a script in REPL mode $ run-mcp -- npx -y some-mcp-server # Test an npx server $ run-mcp --out-dir ./test-output # Agent mode with options $ run-mcp --out-dir ./screenshots -- node srv.js # REPL mode with options

Watch Mode

When developing an MCP server, use --watch (or -w) to automatically reconnect whenever your source files change. This eliminates the manual reconnect step from your edit-test loop:

run-mcp -w -- node my-server.js

On each file change, run-mcp will:

1. Detect the changed files (debounced to 500ms to batch rapid saves)
2. Disconnect from the current server process
3. Reconnect to a fresh instance
4. Show a diff of what primitives changed (tools added/removed/modified, resources, prompts)

Common directories like node_modules, .git, dist, and build are automatically ignored.

Headless Mode (Single-Shot CI/CD)

For CI/CD pipelines, shell scripts, or parsing via jq, run-mcp exposes a suite of headless subcommands that pipe clean JSON to stdout and isolate standard errors and progress updates to stderr.

⚠️ Double-Dash -- Separator

To prevent argument parsing conflicts between run-mcp and the target server, you should separate the target command with a double-dash -- when the target command itself contains flags or options.

• Required when the target command has options/flags:

  run-mcp list-tools -- node my-server.js --verbose
  

  (Must use -- so --verbose is passed to your server, not parsed as an option for run-mcp.)
• Optional when the target command has no options/flags:

  run-mcp list-tools node my-server.js
  

  (Runs successfully without --.)

⚡ HTTPie-Style Shorthand Arguments

Instead of escaping complex JSON strings on the command line, you can provide arguments using simple key-value shorthand notation:

• key=value -> evaluated as a string
• key:=json_val -> parsed as a JSON primitive (boolean, number, array, object, null)

Example:

# Call a tool using shorthand arguments
run-mcp call greet name=Alice count:=5 -- node my-server.js

🔄 Stateful/Persistent CLI Sessions

Normally, every headless command spawns a fresh process of the target server, which is slow and discards connection state. By passing --session <name>, run-mcp will spawn a persistent background daemon on the first call. Subsequent commands will dynamically attach to the same running session:

# Spawns a background session daemon & launches a browser
run-mcp call browser_launch headless:=true --session main -- node browser-server.js

# Navigates the browser on the active running session (no target command needed!)
run-mcp call browser_navigate url=https://google.com --session main

# Closes the session and stops the background target server
run-mcp close-session main

Available Headless Subcommands

• call [options] <tool> [json_args] [target_command...]
• list-tools [options] [target_command...]
• list-resources [options] [target_command...]
• list-prompts [options] [target_command...]
• read [options] <uri> [target_command...]
• describe [options] <tool> [target_command...]
• get-prompt [options] <name> [json_args] [target_command...]
• daemon [options] <session_name> [target_command...]
• close-session <session_name>
• validate [options] [target_command...]
• proxy [options] [target_command...]

Use run-mcp <subcommand> --help for specific command options.

Agent Use Cases

Dynamic Testing

When an AI agent is actively developing an MCP server, it needs to test it. Standard MCP clients require updating a configuration file (mcp.json) and restarting the agent session entirely.

run-mcp solves this by giving the agent a suite of tools to dynamically spawn, inspect, and test local MCP servers on the fly.

How to use: Add run-mcp to your agent's MCP configuration using npx:

{
  "mcpServers": {
    "run-mcp": {
      "command": "npx",
      "args": ["-y", "run-mcp"]
    }
  }
}

Then use these tools from your agent:

Tool	Description
connect_to_mcp	Spawn and connect (use include to get tools/resources/prompts)
call_mcp_primitive	Call a tool, read a resource, or get a prompt (auto-connects)
list_mcp_primitives	List tools, resources, and/or prompts
find_tools	Search tools by relevance (compact, avoids the tools tax)
read_result	Page through an oversized result spilled to disk
disconnect_from_mcp	Tear down and reconnect after changes
mcp_server_status	Check connection status
get_mcp_server_stderr	View target server stderr output
validate_mcp_server	Validate an MCP server command and collect diagnostics
search_all_local_mcp_servers	Scan and search all local MCP servers for a query

REPL Mode Commands

Once connected via run-mcp <command>, the following shorthand commands are available:

Command	Description
tools/list	List all available tools
tools/describe <name>	Show a tool's input schema
tools/call <name> [json] [opts]	Call a tool (interactive if no json)
tools/scaffold <name>	Generate argument template for a tool
find <query>	Find tools by relevance to a query
resources/list	List all available resources
resources/read <uri>	Read a resource by URI
resources/templates	List resource templates
resources/subscribe <uri>	Subscribe to resource changes
resources/unsubscribe <uri>	Unsubscribe from resource changes
prompts/list	List all available prompts
prompts/get <name> [json_args]	Get a prompt with arguments
ping	Verify connection, show round-trip time
log-level <level>	Set server logging verbosity
`history [count	clear]`
`notifications [count	clear]`
roots/list	Show configured client roots
roots/add <uri> [name]	Add a root directory
roots/remove <uri>	Remove a root directory
!! / last	Re-run the last command
reconnect	Disconnect and reconnect
timing	Show tool call performance stats
status	Show target server status

Examples

# List available tools
> tools/list

# Inspect a tool's schema
> tools/describe screenshot

# Call a tool with arguments
> tools/call screenshot {"target": "#loginBtn"}

# Call with a custom timeout (5 seconds)
> tools/call long_running_tool {} --timeout 5000

# Arguments with spaces work fine
> tools/call send_message {"text": "hello world", "channel": "general"}

Direct Inline Tool Calls & Shorthand Arguments

Instead of prefixing every tool call with tools/call, you can invoke any target server tool directly by name, and provide arguments in shorthand key-value form:

# Direct inline tool execution with HTTPie shorthand parameters
> greet name=Bob count:=3

Interactive Wizard & Argument Memory

If you invoke a tool without JSON arguments, run-mcp will guide you through an interactive scaffolding wizard:

> tools/call send_message
✔ text (string) Message text to send: Hello World!
✔ Select optional arguments to provide: channel
✔ channel (string) The Slack channel: general
✔ Execute? Yes
  Calling send_message...

run-mcp actively remembers your inputs across identical interactive calls, scaffolding defaults based on your last execution! Use tools/forget or --clear if you need a clean slate.

Script Mode

You can automate REPL commands by writing them to a file:

# commands.txt
tools/list
tools/call get_status {}
tools/call screenshot {"save_path": "/tmp/test.png"}

run-mcp -s commands.txt -- node my-server.js

• Lines starting with # are treated as comments
• Exits with code 0 on success, 1 on first error

Compressing Proxy Mode — Beat the "Tools Tax"

A powerful MCP server can expose dozens or hundreds of tools; sending every name, description, and JSON Schema to the model up front wastes thousands of tokens before the agent does any work. run-mcp proxy sits in front of a backend server and replaces its full catalog with a tiny discovery-on-demand surface:

• get_tool_schema — its description embeds a compact <tool>name(args): summary</tool> catalog; call it with a tool name to get that tool's full schema on demand.
• invoke_tool — call the chosen tool by name with a JSON input object.
• list_tools — added only at max compression.

Configure it as the command your MCP client spawns:

{
  "mcpServers": {
    "my-server": {
      "command": "run-mcp",
      "args": ["proxy", "-c", "medium", "--", "node", "path/to/actual-server.js"]
    }
  }
}

Fronting a whole fleet (multiplexer)

Point run-mcp at a standard mcpServers config (the same shape every agent tool uses) and it fronts them all through one entry, with Dynamic Context Loading:

run-mcp proxy -c medium --config ./mcp-fleet.json
# or, without a file:
run-mcp proxy --multi-server "github=npx -y @modelcontextprotocol/server-github" \
              --multi-server "browser=node ./browser-mcp/dist/index.js"

With two or more backends the surface becomes a five-tool discovery hierarchy — your context stays tiny no matter how many servers or tools you front:

• list_servers — Level 1: which servers exist and what each is for (this overview is embedded in the tool's own description, so it costs nothing until you go deeper). Descriptions come from each server's own MCP instructions, its tool catalog, or an optional "description" you add per server in the config.
• find_tools — cross-server BM25 search; returns ranked, namespaced tool names.
• list_server_tools — Level 2: one server's compressed catalog.
• get_tool_schema / invoke_tool — Level 3 + execute; tool names are namespaced server__tool, and calls route to the owning backend. One backend failing to start doesn't sink the proxy.

Compression levels (-c, default medium)

Level	Catalog entry format
low	<tool>name(args): full description</tool>
medium	<tool>name(args): first sentence</tool>
high	<tool>name(args)</tool>
max	<tool>name</tool> (+ adds a list_tools tool)

Options

• -c, --compression <level> — low / medium / high / max.
• --include-tools <names...> / --exclude-tools <names...> — restrict the exposed backend tools (applied before compression).
• --compress-output — also minify backend tool output (lossless JSON minify).
• --sandbox <mode>, --transport <mode> — forwarded to the backend.

Calls routed through invoke_tool still pass through the interceptor pipeline (tool-poisoning scan, media extraction, truncation, optional output compression).

Agent Server Mode — How It Works

Run with no target command (or --mcp), run-mcp is itself an MCP server that exposes tools (connect_to_mcp, call_mcp_primitive, find_tools, …) so an agent can dynamically spawn and test local MCP servers. Tool-call responses are processed through the interceptor pipeline:

Feature	Behavior
Image extraction	type: "image" responses with base64 data are saved to disk. Replaced with [Image saved to /path/to/img.png (24KB)]
Audio extraction	type: "audio" responses with base64 data are saved to disk. Replaced with [Audio saved to /path/to/audio.wav (12KB)]
Base64 detection	Text responses that are entirely base64-encoded (1000+ chars) are also saved as images
Timeouts	Tool calls are wrapped in a configurable timeout (default 5 minutes, use --timeout to change)
Truncation	Text exceeding the limit (default 50K chars, --max-text to change) is saved in full to disk; the reply keeps the head plus a result id, navigable via the read_result tool

Sandboxing & Outbound Data Exfiltration Protection

run-mcp features a comprehensive multi-layered sandboxing engine designed to protect local systems and credentials from malicious or buggy MCP servers.

🛡️ Sandboxing Modes

You can restrict a target server's execution footprint using the --sandbox flag:

• none (Default): No sandboxing. The target server runs with full user privileges.
• auto: Automatically selects the most restrictive sandboxing system available on the host OS.
• native: Uses OS-level native isolation:
  • macOS: Utilizes the Seatbelt (App Sandbox) framework (sandbox-exec).
  • Linux: Utilizes bubblewrap (bwrap) containerization.
  • Windows: Utilizes @microsoft/mxc-sdk App Container sandboxing (requires the package to be present).
• docker: Spawns the target command inside a fresh, network-disabled ephemeral Docker container (node:20 or python:3 depending on the command).
• audit: Runs the server under a special non-enforcing native sandbox mode that permits operations but logs all network activity to the console.

🌐 Outbound Network Proxy Auditing

When a sandboxed server is granted outbound network access (e.g., using --allow-net), run-mcp automatically spawns a zero-dependency local Network Audit Proxy.

• All outbound HTTP/HTTPS traffic is forced through the proxy using environment variables.
• Target endpoints and protocols (including HTTPS CONNECT tunnels) are transparently logged to stderr in distinct cyan color:

  🌐 [NETWORK AUDIT] HTTP request to: http://example.com/api/v1/data
  🌐 [NETWORK AUDIT] HTTPS connection established to: github.com
  

• Permits outbound traffic while providing complete visibility into where the server is sending data.

🔑 Automatic Credential Protection (Deny-Wins)

When outbound network capability is enabled, run-mcp automatically safeguards your local configuration files and private keys from exfiltration. By default, the sandbox denies access to the following directories:

• ~/.ssh (SSH private keys and configs)
• ~/.aws (AWS credentials)
• ~/.kube (Kubernetes configurations)
• ~/.config/gcloud (Google Cloud SDK credentials)
• ~/.netrc and ~/.npmrc (Authentication files)

Access is strictly blocked using Deny-Wins precedence unless a folder is explicitly whitelisted.

[!NOTE] Platform Support for Deny Rules:

• macOS (native / Seatbelt): Deny rules are natively enforced at the OS kernel level.
• Docker & Linux (native / Bubblewrap): Deny rules within the workspace are enforced by masking directories/files (overlaying empty files or tmpfs mounts).
• Windows (native / MXC): The @microsoft/mxc-sdk is strictly allowlist-based and does not support exclusions within allowed paths; a warning is printed to stderr if deny rules are configured.

⚙️ Capabilities & Configuration

You can configure sandbox rules on the command line or using structured JSON settings files.

CLI Overrides

Pass these flags after run-mcp and before the target command:

• --sandbox <mode>: Set sandbox execution mode (auto, native, docker, audit, none).
• --allow-read <paths...>: Allow reading specific host directories.
• --allow-write <paths...>: Allow writing to specific host directories.
• --allow-net <domains...>: Allow outbound network access to specific domains.
• --deny-read <paths...>: Deny reading specific host directories.
• --deny-write <paths...>: Deny writing to specific host directories.
• --deny-net <domains...>: Deny outbound network access to specific domains.

Configuration Scopes

run-mcp resolves settings hierarchically, allowing both administrator enforcement and developer configuration:

1. Managed (Enterprise): System-wide read-only overrides (/Library/Application Support/run-mcp/settings.json, C:\Program Files\run-mcp\settings.json, /etc/run-mcp/settings.json).
2. User (Global): Personal defaults (~/.gemini/antigravity-ide/settings.json or equivalent).
3. Project: Shared settings within a repository (<workspace>/.run-mcp.json).
4. Local: Developer-specific project settings (<workspace>/.run-mcp.local.json).

Example Settings File (.run-mcp.json):

{
  "sandbox": {
    "mode": "native",
    "allowRead": ["/usr/local/bin"],
    "allowNet": ["*.api.github.com"],
    "denyRead": ["~/.ssh"]
  }
}

Architecture

For the detailed system architecture diagram and source module directory map, please refer to AGENTS.md.

Development

# Install dependencies
npm install

# Build (one-time)
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Run directly
node dist/index.js -- <target_command...>

License

MIT