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

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github/workflows		.github/workflows
docs		docs
src		src
test		test
.cursorindexingignore		.cursorindexingignore
.editorconfig		.editorconfig
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
IMPROVING_FACTORING_PLAN.md		IMPROVING_FACTORING_PLAN.md
LICENSE		LICENSE
MCP_TESTING_GUIDE.md		MCP_TESTING_GUIDE.md
README.md		README.md
SESSION_STATE_DESIGN.md		SESSION_STATE_DESIGN.md
TASKS_AND_ELICITATIONS.md		TASKS_AND_ELICITATIONS.md
bun.lock		bun.lock
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

emceepee

Why?

Quick Start

1. Add to your MCP client

2. Connect to servers mid-session

How It Works

Server Transports

HTTP/SSE Transport

Stdio Transport (Process Management)

Process Lifecycle Events

Restart Configuration

Tools

Server Management

Tools

Resources

Prompts

Notifications & Logs

Sampling (bidirectional LLM requests)

Elicitations (user input requests)

Tasks & Activity

Timers

Codemode (Reduced-Context API)

Codemode API

Tools

The mcp.* API

Example: Multi-Step Operation

Security Features

Configuration

Context Info

Installation

Usage

stdio transport (Claude Code, Claude Desktop)

HTTP transport (web clients, custom integrations)

Configuration File

Example Session

Library Usage

MCPStdioClient

IMCPClient Interface

Development

Testing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages