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:

REPL Mode Commands

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

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:

What the proxy intercepts

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

Architecture

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

Modules

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