mcpcodeserver

- List connected child servers— Uselist_serversto see which sub-servers are available and active.
- Get TypeScript definitions for tools— Callget_tool_definitionsto retrieve typed function signatures for all or specific servers’ tools.
- Execute multi-tool workflows as code— Write TypeScript that chains multiple tool calls, loops, and conditionals viagenerate_and_execute_code.
- Filter tool definitions by server— Passserver_namestoget_tool_definitionsto reduce context usage and focus on relevant tools.
- Handle errors in tool sequences— Use try/catch inside generated code to recover from individual tool failures without aborting the whole workflow.

A Model Context Protocol (MCP) proxy server that translates tool calls into TypeScript code generation. Instead of making multiple tool calls back and forth, LLMs can write TypeScript code that calls multiple tools naturally, reducing token overhead and leveraging the LLM's superior code generation capabilities.

LLMs make multiple sequential tool calls, burning tokens and struggling with complex workflows:

- ❌ Multiple round-trips between LLM and tools
- ❌ Complex tool calling sequences are error-prone
- ❌ Data cannot easily be passed between tools
- ❌ Limited error handling and control flow

LLMs write TypeScript code that calls multiple tools naturally:

- ✅ Write code to call multiple tools in sequence
- ✅ Use variables, loops, and conditionals naturally
- ✅ Better error handling with try/catch
- ✅ Reduce token usage by combining operations
- ✅ Leverage LLM's strong code generation capabilities
- Install mcpcodeserverin your MCP client (see installation section below)
- Create anmcp.jsonconfiguration file with your child MCP servers
- Start using it- your LLM can now generate and execute TypeScript code that calls your tools

// Instead of multiple tool calls, write code like this: const files = await filesystem.list_directory({ path: "/tmp" }); const results = await Promise.all( files.map(file => filesystem.read_file({ path: file.path })) ); return results.filter(content => content.includes("important"));

mcpcodeserveris a unique MCP server that:

- Acts as an MCP client to connect to one or more child MCP servers
- Discovers all tools from child servers
- Exposes three powerful tools to parent LLM clients:
- list_servers- Lists all available sub-servers connected to this MCP server
- get_tool_definitions- Returns TypeScript type definitions for discovered tools (optionally filtered by server)
- generate_and_execute_code- Generates and executes TypeScript code that calls those tools in a sandbox

This architecture allows LLMs to orchestrate complex multi-tool workflows by writing code instead of making sequential tool calls, which is often more efficient and natural for modern language models.

This approach is inspired by recent research showing that LLMs perform better when generating executable code rather than making direct tool calls:

-

CodeAct: Your LLM Agent Acts Better when Generating Code(Apple, ICML 2024) - Demonstrates that LLM agents achieve up to 20% higher success rates when using executable Python code as a unified action space instead of pre-defined tool calling formats.

Cloudflare Code Mode- A similar implementation that converts MCP tools into TypeScript APIs, showing that "LLMs are better at writing code to call MCP, than at calling MCP directly."

// List available servers const servers = await list_servers({}); // Returns: ["pizzashop", "filesystem", "memory"] // Get all tool definitions const allTools = await get_tool_definitions({}); // Get only pizzashop tools const pizzashopTools = await get_tool_definitions({ server_names: ["pizzashop"] });

mcpcodeserver supports pass-through of advanced MCP protocol features when both parent and child servers support them:

- Elicitation: Child servers can request user input during tool execution, which is passed through to parent clients
- Roots: Lists and aggregates roots from all child servers, providing a unified view of available resources
- Sampling: Enables LLM sampling requests to be passed through to child servers for advanced AI capabilities

These features are automatically advertised to parent clients and work seamlessly when supported by the underlying child MCP servers.

Try it immediately with npx (no installation required):

# From GitHub npx github:zbowling/mcpcodeserver --help # Or when published to npm npx mcpcodeserver --help

- Node.js >= v18.0.0
- Cursor, Claude Code, VSCode, Windsurf or another MCP Client

To install mcpcodeserver for any client automatically viaSmithery:

npx -y @smithery/cli@latest install mcpcodeserver --client <client-name> --key <smithery-key>

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

Cursor Remote Server Connection (if you set up HTTP transport)

{ "mcpServers": { "mcpcodeserver": { "url": "http://localhost:3000/mcp" } } }

Run this command. SeeClaude Code MCP docsfor more info.

claude mcp add mcpcodeserver -- npx -y mcpcodeserver --config /path/to/your/mcp.json

claude mcp add --transport http mcpcodeserver http://localhost:3000/mcp

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

ForContinue,Cline, andRooCode, add to your configuration:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

Run this command in your terminal. SeeAmp MCP docsfor more info.

amp mcp add mcpcodeserver -- npx -y mcpcodeserver --config /path/to/your/mcp.json

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

{ mcpServers = { mcpcodeserver = { command = "npx", args = {"-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"} } } }

(setq mcp-servers '((mcpcodeserver :command "npx" :args ("-y" "mcpcodeserver" "--config" "/path/to/your/mcp.json"))))

ForIntelliJ IDEA,WebStorm,PyCharm, andAndroid Studio, add to your MCP settings:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

ForCodeium,Tabnine,GitHub Copilot, andAmazon CodeWhisperer, add to your MCP settings:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

ForReplit,CodeSandbox,StackBlitz,GitPod,GitHub Codespaces,GitLab Web IDE, andBitbucket Cloud, add to your MCP settings:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

ForXcode,Fleet,Sourcegraph, andJetBrains Gateway, add to your MCP configuration:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

For remote development environments, you can also use HTTP transport:

{ "mcpServers": { "mcpcodeserver": { "url": "http://your-server:3000/mcp" } } }

Create anmcp.jsonconfiguration file to define your child MCP servers:

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], "env": { "DEBUG": "false" } }, "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "your-api-key" } } } }

# Install dependencies (using Bun for faster performance) bun install # Or with npm npm install # Build the project bun run build # Test the built server bun dist/index.js --help

Note: This project uses Bun for better performance, but npm/node also work fine.

If you encounterERR_MODULE_NOT_FOUND, try usingbunxinstead ofnpx:

{ "mcpServers": { "mcpcodeserver": { "command": "bunx", "args": ["-y", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

For errors likeError: Cannot find module, try the--experimental-vm-modulesflag:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "--node-options=--experimental-vm-modules", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

Use the--experimental-fetchflag to bypass TLS-related problems:

{ "mcpServers": { "mcpcodeserver": { "command": "npx", "args": ["-y", "--node-options=--experimental-fetch", "mcpcodeserver", "--config", "/path/to/your/mcp.json"] } } }

- Try adding@latestto the package name
- Usebunxas an alternative tonpx
- Consider usingdenoas another alternative
- Ensure you're using Node.js v18 or higher for native fetch support

- Make sure yourmcp.jsonfile is valid JSON
- Check that all child server commands are available in your PATH
- Verify that child servers can start independently
- Check file permissions for the config file path

npx -y @modelcontextprotocol/inspector npx mcpcodeserver --config /path/to/your/mcp.json

mcpcodeserveraccepts the following CLI flags:

- --config <path>– Path to the MCP configuration file (default:./mcp.json)
- --transport <stdio|http>– Transport to use (stdioby default). Note that HTTP transport automatically provides both HTTP and SSE endpoints
- --port <number>– Port to listen on when usinghttptransport (default3000)
- --help– Show help message

Example with HTTP transport and port 8080:

npx mcpcodeserver --config /path/to/mcp.json --transport http --port 8080

npx mcpcodeserver --config /path/to/mcp.json --transport stdio

You can use environment variables for configuration:

- MCP_CONFIG_PATH– Path to the MCP configuration file (alternative to--config)
- MCP_TRANSPORT– Transport type (alternative to--transport)
- MCP_PORT– Port number for HTTP transport (alternative to--port)

# .env MCP_CONFIG_PATH=/path/to/your/mcp.json MCP_TRANSPORT=stdio