emceepee

Connect to any MCP server, anytime. Access the full MCP protocol through tools.

npx emceepee

Why?

Problem 1: Static connections. Most MCP clients only connect to servers at startup. Want to connect to a new server mid-session? Restart everything.

Problem 2: Incomplete protocol support. MCP has rich features—resources, prompts, notifications, sampling, elicitations—but many clients only implement tools. Those features? Inaccessible.

emceepee solves both. It's a proxy that exposes the entire MCP protocol as tools. Any client that supports tool calling can now:

• Connect to new MCP servers dynamically (HTTP or stdio)
• Spawn and manage MCP server processes with automatic crash recovery
• Access resources and resource templates
• Use prompts
• Receive notifications and logs (with source filtering)
• Handle sampling requests (bidirectional LLM calls)
• Handle elicitations (user input requests)

Quick Start

1. Add to your MCP client

Claude Code / Claude Desktop (.mcp.json):

{
  "mcpServers": {
    "emceepee": {
      "command": "npx",
      "args": ["emceepee"]
    }
  }
}

Other clients — point to the HTTP server:

npx emceepee-http  # runs on http://localhost:8080/mcp

2. Connect to servers mid-session

Ask your LLM:

"Connect to http://localhost:3001/mcp and show me what it can do"

The LLM will use emceepee's tools to connect, explore, and interact with the server.

---

How It Works

┌────────────┐     ┌───────────┐     ┌──────────────┐
│ MCP Client │────▶│ emceepee  │────▶│ MCP Server 1 │
│            │     │           │     └──────────────┘
│ (tools     │◀────│  (proxy)  │────▶┌──────────────┐
│   only)    │     │           │     │ MCP Server 2 │
└────────────┘     └───────────┘     └──────────────┘

emceepee exposes a static set of tools that never change. These tools provide access to the full MCP protocol, letting any tool-capable client use features it doesn't natively support.

Server Transports

emceepee supports two transport types for connecting to backend MCP servers:

HTTP/SSE Transport

Connect to remote MCP servers over HTTP with Server-Sent Events:

add_server(name: "myserver", url: "http://localhost:3001/mcp")

Stdio Transport (Process Management)

Spawn and manage MCP servers as child processes communicating via stdin/stdout:

add_server(name: "myserver", command: "node", args: ["server.js"])

Stdio features:

• Automatic crash recovery with exponential backoff restart
• Stderr capture for debugging (exposed via get_logs with source: "stderr")
• Lifecycle events for monitoring process state
• Configurable restart behavior (max attempts, delays, backoff multiplier)

Process Lifecycle Events

When using stdio transport, emceepee tracks the full process lifecycle:

Event	Description
process_started	Process spawned successfully
process_crashed	Process exited unexpectedly
restarting	Attempting to restart (with attempt count)
restarted	Successfully restarted after crash
restart_failed	Max restart attempts exceeded
process_stopped	Process stopped cleanly

Restart Configuration

Customize crash recovery behavior per server:

{
  "restartConfig": {
    "enabled": true,
    "maxAttempts": 5,
    "baseDelayMs": 1000,
    "maxDelayMs": 60000,
    "backoffMultiplier": 2
  }
}

Tools

Server Management

Tool	Description
add_server	Connect to a backend MCP server
remove_server	Disconnect from a server
list_servers	List connected servers with status

Tools

Tool	Description
list_tools	List tools from connected servers (with regex filtering)
execute_tool	Run a tool on a backend server

Resources

Tool	Description
list_resources	List available resources
list_resource_templates	List resource templates
read_resource	Fetch a resource by URI
subscribe_resource	Subscribe to resource change notifications
unsubscribe_resource	Unsubscribe from resource change notifications

Prompts

Tool	Description
list_prompts	List available prompts
get_prompt	Get a prompt with arguments

Notifications & Logs

Tool	Description
get_notifications	Get buffered server notifications
get_logs	Get buffered log messages with source filtering

The get_logs tool supports filtering by log source:

• protocol: MCP protocol messages and notifications
• stderr: Process stderr output (for stdio servers)
• stdout: Process stdout capture (for local HTTP servers)

Example: Get only protocol logs by excluding stderr/stdout:

{ "exclude_sources": ["stderr", "stdout"] }

Sampling (bidirectional LLM requests)

Tool	Description
get_sampling_requests	Get pending requests from servers wanting LLM completions
respond_to_sampling	Send an LLM response back to the server

Elicitations (user input requests)

Tool	Description
get_elicitations	Get pending requests for user input
respond_to_elicitation	Send user input back to the server

Tasks & Activity

Tool	Description
list_tasks	List background tasks
get_task	Get task status
cancel_task	Cancel a running task
await_activity	Wait for server events (polling)

Timers

Tool	Description
set_timer	Create a timer that fires after a duration
list_timers	List all timers
get_timer	Get timer details
delete_timer	Delete a timer (returns timer body)

Codemode (Reduced-Context API)

Tool	Description
codemode_search	Search for capabilities across all servers
codemode_execute	Execute JavaScript with access to mcp.* API

Codemode API

Codemode is a reduced-context API that exposes just 2 tools instead of the full set. This dramatically reduces token usage when AI needs to perform complex multi-step MCP operations.

Tools

codemode_search - Search for tools, resources, prompts, or servers using regex patterns:

{
  "query": "file|read",
  "type": "tools",
  "server": "myserver",
  "includeSchemas": false
}

codemode_execute - Run JavaScript in a sandboxed environment:

{
  "code": "const tools = await mcp.listTools(); return tools.length;",
  "timeout": 30000
}

The mcp.* API

Inside codemode_execute, your code has access to:

// Server discovery
await mcp.listServers()

// Tool operations
await mcp.listTools(serverPattern?)
await mcp.callTool(server, tool, args?)

// Resource operations
await mcp.listResources(serverPattern?)
await mcp.listResourceTemplates(serverPattern?)
await mcp.readResource(server, uri)

// Prompt operations
await mcp.listPrompts(serverPattern?)
await mcp.getPrompt(server, name, args?)

// Utilities
await mcp.sleep(ms)    // max 5 seconds per call
mcp.log(...args)       // captured in result.logs

Example: Multi-Step Operation

// Find all "search" tools and call the first one
const tools = await mcp.listTools();
const searchTools = tools.filter(t => t.name.includes('search'));

if (searchTools.length === 0) {
  return { error: 'No search tools found' };
}

const tool = searchTools[0];
mcp.log(`Calling ${tool.server}/${tool.name}`);

const result = await mcp.callTool(tool.server, tool.name, {
  query: 'example'
});

return {
  tool: tool.name,
  server: tool.server,
  result: result.content
};

Security Features

• Sandboxed execution - Blocked globals: process, require, eval, fetch, setTimeout, Function, etc.
• Timeout enforcement - 1 second to 5 minutes (default 30s)
• MCP call limits - Maximum 100 mcp.* calls per execution
• Code size limits - Maximum 100KB of code

Configuration

Codemode is enabled by default. To disable:

CLI flag:

npx emceepee --no-codemode
npx emceepee-http --no-codemode

Environment variable:

EMCEEPEE_NO_CODEMODE=1 npx emceepee

Library usage:

registerTools(server, sessionManager, sessions, requestTracker, {
  codemodeEnabled: false
});

Context Info

Every tool response may include additional context information as a second JSON text block. This provides real-time status without requiring explicit polling:

{
  "content": [
    { "type": "text", "text": "Tool result here" },
    { "type": "text", "text": "{\"pending_client\":{\"sampling\":1,\"elicitation\":0},\"expired_timers\":[{\"id\":\"...\",\"message\":\"Check status\",\"expiredAt\":\"...\"}],\"notifications\":[...]}" }
  ]
}

Context info fields:

Field	Description
pending_client.sampling	Number of pending sampling requests (urgent - servers are blocked)
pending_client.elicitation	Number of pending elicitation requests (urgent - servers are blocked)
expired_timers	Timers that have fired since the last tool call (cleared after delivery)
notifications	Buffered notifications from backend servers (cleared after delivery)

Context info is only included when there's something to report.

Installation

# Run directly
npx emceepee

# Or install globally
npm install -g emceepee

Usage

stdio transport (Claude Code, Claude Desktop)

npx emceepee

HTTP transport (web clients, custom integrations)

# Default port 8080
npx emceepee-http

# Custom port
PORT=9000 npx emceepee-http

# With pre-configured servers
npx emceepee-http --config servers.json

Configuration File

Pre-configure backend servers (HTTP and stdio):

{
  "servers": [
    {
      "name": "remote-server",
      "url": "http://localhost:3001/mcp"
    },
    {
      "name": "local-server",
      "type": "stdio",
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": { "DEBUG": "true" },
      "restartConfig": {
        "maxAttempts": 3,
        "baseDelayMs": 1000
      }
    }
  ]
}

Example Session

User: Connect to http://localhost:3001/mcp as "gameserver"

LLM: [uses add_server]
Connected to gameserver successfully.

User: What can it do?

LLM: [uses list_tools, list_resources, list_prompts]
gameserver has:
- 3 tools: screenshot, send_chat, move
- 2 resources: player_state, world_info
- 1 prompt: describe_scene

User: Get the player state

LLM: [uses read_resource with uri="minecraft://state"]
Player is at position (100, 64, -200), health: 18/20

Library Usage

emceepee can also be used as a library for building custom MCP integrations:

MCPStdioClient

Spawn and manage MCP servers as child processes:

import { MCPStdioClient } from "emceepee";

const client = new MCPStdioClient({
  name: "my-server",
  command: "node",
  args: ["server.js"],
  restartConfig: {
    maxAttempts: 5,
    baseDelayMs: 1000,
  },
  onLifecycleEvent: (event) => {
    console.log(`${event.event}: ${JSON.stringify(event)}`);
  },
  onLog: (log) => {
    if (log.source === "stderr") {
      console.error(`[stderr] ${log.data}`);
    }
  },
});

await client.connect();

// Use the client
const tools = await client.listTools();
const result = await client.callTool("my-tool", { arg: "value" });

// Clean shutdown
await client.disconnect();

IMCPClient Interface

Both HTTP and stdio clients implement the common IMCPClient interface:

import { IMCPClient, isStdioClient, isHttpClient } from "emceepee";

function handleClient(client: IMCPClient) {
  if (isStdioClient(client)) {
    // Stdio-specific operations (e.g., access stderr buffer)
  } else if (isHttpClient(client)) {
    // HTTP-specific operations
  }

  // Common operations work on both
  const tools = await client.listTools();
  const info = client.getInfo();
}

Development

bun install              # Install dependencies
bun run dev              # stdio server (development)
bun run dev:http         # HTTP server (development)
bun run check            # TypeScript + ESLint
bun run test             # Run tests
bun run build            # Production build

Testing

bun run test             # Run all tests
bun run test:stdio       # Run stdio client tests
bun run test:codemode    # Run codemode tests

Tests cover:

• Stdio client: Connection lifecycle, tool invocation, stderr capture, crash recovery, lifecycle events
• Codemode: Sandbox isolation, timeout enforcement, API bindings, search/execute functionality, error handling

License

MIT © Andrew Jefferson