run-mcp

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

run-mcp operates in two modes:

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 repl) — A headless CLI for human developers to manually test and explore MCP servers using short, memorable commands (tools/call, status, etc.).

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
• Truncating huge text responses to protect context budgets

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 repl node path/to/my-mcp-server.js

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

# Or start it without arguments to open the interactive server discovery menu!
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...]

Options: -V, --version Show version number -o, --out-dir Directory to save intercepted images and audio -t, --timeout Default tool call timeout in milliseconds (default: 300000) (Agent Mode only) --max-text Max text response length before truncation (default: 50000) (Agent Mode only) --mcp Force start Agent Server mode even if run interactively without arguments -s, --script Read commands from a file instead of stdin (REPL Mode only) -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 node my-server.js -s test.txt # 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

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. You must use -- to separate the command from the target server options.

# Get tool names as a flat list
run-mcp list-tools -- node my-server.js | jq -r '.[].name'

# Call a tool and extract a field  
run-mcp call generate '{"prompt":"test"}' -- node my-server.js | jq '.content[0].text'

# Read a resource and pipe to file
run-mcp read docs://config -- node my-server.js > config.json

Available subcommands:

• call <tool> [json_args]
• list-tools
• list-resources
• list-prompts
• read <uri>
• describe <tool>
• get-prompt <name> [json_args]

Use run-mcp <subcommand> --help for specific command options (like --timeout and --raw).

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 to a local MCP server. Use include to get tools/resources/prompts inline. Shows a diff on reconnect.
disconnect_from_mcp	Tear down the connection
mcp_server_status	Check connection status
call_mcp_primitive	Call a tool, read a resource, or get a prompt. Auto-connects if not already connected. Use disconnect_after for one-shot tests.
list_mcp_primitives	List tools, resources, and/or prompts on the connected server
get_mcp_server_stderr	View target server stderr output
list_available_mcp_servers	Discover other local MCP servers configured on the host machine

REPL Mode Commands

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

Command	Description
explore	Open interactive fuzzy-search selector for tools, resources, and prompts
tools/list	List all tools exposed by the target server
tools/describe <name>	Show a tool's full input schema
tools/call <name> [json] [--clear]	Call a tool. Launch interactive wizard if no JSON provided. Use --clear to ignore remembered arguments.
tools/forget [name]	Clear remembered interactive arguments for a tool, or all tools if no name provided.
status	Show target server status (PID, uptime, connection)
help	Show available commands
exit / quit	Disconnect and exit

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"}

### Interactive Wizard & Argument Memory

If you invoke a tool without JSON arguments, `run-mcp` will guide you through an interactive scaffolding wizard:
```bash
> 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:

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

run-mcp repl node my-server.js --script commands.txt

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

Proxy Mode — How It Works

In proxy mode, run-mcp acts as an MCP server itself. Configure it as the command your AI agent spawns:

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

What the proxy forwards

The proxy dynamically mirrors the target server's capabilities. All MCP primitives that the target supports are forwarded transparently:

Primitive	Forwarded?
Tools (tools/list, tools/call)	✅ Always (with interception)
Resources (resources/list, resources/read, resources/templates/list)	✅ If target supports
Prompts (prompts/list, prompts/get)	✅ If target supports
Logging (logging/setLevel)	✅ If target supports
Completion (completion/complete)	✅ If target supports
Notifications (list changes, logging)	✅ Forwarded from target to agent
Tool annotations (readOnlyHint, destructiveHint, etc.)	✅ Preserved as-is
Pagination (nextCursor / cursor)	✅ Passed through

What the proxy intercepts

Tool call responses are processed through the interceptor pipeline. All other primitives pass through untouched.

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 60s, use --timeout to change)
Truncation	Text responses exceeding the limit (default 50K chars, use --max-text to change) are truncated

Architecture

┌─────────────────────┐         ┌─────────────────────┐
│                     │  stdio  │                     │
│   AI Agent / REPL   │◄───────►│     run-mcp         │
│                     │         │                     │
└─────────────────────┘         │  ┌───────────────┐  │
                                │  │  Interceptor   │  │
                                │  │  • Timeouts    │  │
                                │  │  • Image Save  │  │
                                │  │  • Truncation  │  │
                                │  └───────┬───────┘  │
                                │          │          │
                                │  ┌───────▼───────┐  │
                                │  │ TargetManager  │  │
                                │  │ (MCP Client)   │  │
                                │  └───────┬───────┘  │
                                └──────────┼──────────┘
                                           │ stdio
                                ┌──────────▼──────────┐
                                │  Target MCP Server   │
                                │  (child process)     │
                                └─────────────────────┘

Modules

Module	File	Responsibility
TargetManager	src/target-manager.ts	Spawns the target MCP server, manages the MCP Client connection, forwards all MCP primitives (tools, resources, prompts, logging), captures stderr, tracks lifecycle
ResponseInterceptor	src/interceptor.ts	Wraps tool calls with timeouts, extracts base64 images and audio to disk, truncates oversized text
REPLMode	src/repl.ts	Interactive readline REPL with shorthand command parsing and script mode
ProxyMode	src/proxy.ts	MCP Server that transparently forwards all MCP primitives to the target, with tool responses running through the interceptor

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 repl <target_command...>

License

MIT