Code-mode MCP gateway

Run TypeScript with MCP tools, safely.

Code-mode MCP gateway with semantic tool search, typed clients, and CLI generation.

Get started Install GitHub

Local + remote servers

Mix stdio and HTTP MCP servers in one config with JSONC and env substitution.

Typed client surface

Generate a typed interface for tools so your scripts stay readable and refactorable.

Quick run

Package manager

Step 1

bunx mcp-exec serve

Step 2

// ~/.config/mcp-exec/mcp-exec.jsonc
{
  "mcpServers": {
    "local-server": {
      "command": "bun",
      "args": ["server.ts"],
      "cwd": "/path/to/server"
    }
  },
  "serve": { "host": "127.0.0.1", "port": 3000 }
}

Quickstart

A short path that works for local dev and CI. Copy buttons only copy the recommended command or snippet.

Install or run (recommended)

Uses your package manager to run the CLI without a global install.

Run the gateway

Start the serve-first gateway (keep this running in one terminal).

bunx mcp-exec serve

2) Configure servers (JSONC)

Define local stdio servers and/or remote HTTP servers. Supports env var substitution.

// ~/.config/mcp-exec/mcp-exec.jsonc
{
  "mcpServers": {
    "local-server": {
      "command": "bun",
      "args": ["server.ts"],
      "cwd": "/path/to/server"
    }
  },
  "serve": { "host": "127.0.0.1", "port": 3000 }
}

3) Call a tool

Call any MCP tool using server.tool and key=value args.

mcp-exec call local-server.my_tool arg=value

4) Search tools (optional)

Semantic tool search. Requires an embedding provider API key (for example Google).

export GOOGLE_GENERATIVE_AI_API_KEY=...

mcp-exec search "resize image"

Architecture

Two common modes: a serve-first gateway (recommended) or one-shot commands.

Client

Agent / Scripts

Gateway

mcp-exec serve

Manages config, auth, retries, and tool search (optional).

Backends

MCP servers (stdio + HTTP)

Tools

serve

Start the MCP gateway (HTTP or stdio transport)

run

Run TypeScript with MCP tools (file, stdin, or JSON)

call

Call a tool directly (server.tool arg=value)

Semantic search across tool surfaces (optional)

types

Generate a typed MCP client surface

generate-cli

Generate a standalone CLI from a server

config

Import/export/doctor/list config

auth

OAuth login/status/logout helpers for HTTP servers

Privacy

This site is served from Cloudflare Workers. Cloudflare may log basic request metadata for operations. mcp-exec only calls third-party APIs if you configure them (for example embedding providers for semantic tool search).

Read the full privacy policy Contact via GitHub