MCPMan

MCPMan is a versatile MCP server manager that acts as a proxy for multiple MCP servers. It lets you connect to several MCP endpoints at once, generate and run code from natural language prompts, execute JavaScript with access to all connected tools, and manage configurations securely with OAuth 2.1. You can add new servers on the fly without restarting, and you can batch or parallelize tool invocations across servers. The results from tool runs are kept in a centralized $results array for easy reuse.

How to use

You use MCPMan by connecting to one or more MCP servers, then invoking tools to generate code, evaluate expressions, or batch-invoke multiple tools. Start by wiring up the servers you need, then use the built-in code generator to translate natural language descriptions into JavaScript that interacts with your connected tools. When you run code or tool invocations, the outputs are stored in $results so you can reference prior results in subsequent steps.

How to install

Prerequisites you need before installing MCPMan: Node.js and npm (or a compatible runtime). You may also use bun if you prefer that workflow. Follow these concrete steps to get up and running.

# Install dependencies with your preferred runtime
npm install

# If you use bun, you can alternatively install with bun
bun install

# Initialize MCPMan configuration
mcpman init

Configuration and usage notes

MCPMan provides a two-server setup: a local stdio server for direct integration and a remote HTTP server for API-based access. You configure these servers with explicit commands and URLs. The stdio server runs locally and is started with a command and arguments, while the HTTP server connects to a remote MCP endpoint over HTTP.

{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {},
      "disabled": false,
      "timeout": 30000
    },
    "api_server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": {},
      "oauth": {
        "clientName": "mcpman",
        "redirectUrl": "http://localhost:3000/callback",
        "scopes": ["mcp:tools"],
        "clientId": "optional-client-id",
        "clientSecret": "optional-client-secret"
      },
      "disabled": false,
      "timeout": 30000
    }
  }
}

Security and access

MCPMan supports OAuth 2.1 for HTTP transports to secure access to remote MCP endpoints. Ensure you configure client credentials and redirect URLs as needed for your environment, and keep sensitive values out of your code by using environment variables or secret stores where possible.

Configuration reference

Below is a representative configuration for MCPMan with a local stdio server and a remote HTTP server. This is the schema you’ll store in your settings. Adjust the values to match your environment.

{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {},
      "disabled": false,
      "timeout": 30000
    },
    "api_server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": {},
      "oauth": {
        "clientName": "mcpman",
        "redirectUrl": "http://localhost:3000/callback",
        "scopes": ["mcp:tools"],
        "clientId": "optional-client-id",
        "clientSecret": "optional-client-secret"
      },
      "disabled": false,
      "timeout": 30000
    }
  }
}

Troubleshooting

If a server becomes unavailable, MCPMan’s CLI provides commands to test and validate your configuration. Use the test command to verify server connections and tool availability. Check timeouts in the configuration if tool invocations stall or fail to return results promptly.

Notes

The $results array stores outputs from tool invocations, allowing you to reference previous results when chaining tasks. You can run code or evaluate expressions that call across multiple servers, and you can filter the set of available servers when generating code to keep context focused and improve reliability.

Examples

• Generate and execute code to list files in a directory, using only the filesystem MCP server to keep context small.

• Evaluate a function that reads from the filesystem and processes the results, then uses another server for further processing.

Available tools

code

Generate and execute JavaScript code from natural language descriptions using LLMs with TypeScript validation and a unified tool environment.

eval

Execute JavaScript expressions with access to all MCP tools and the $results array.

invoke

Batch invoke multiple MCP tools, with options for parallel or sequential execution across configured servers.

list_servers

List connected MCP servers and their available tools.

help

Provide tool documentation and usage help for specific MCP tools.

install

Dynamically add new MCP servers to your configuration without restarting the running instance.