OneMCP Aggregator

OneMCP is a universal MCP Aggregator that unifies tools from multiple external MCP servers into a single interface. It uses progress-enabled discovery to reduce token usage, improve scalability, and preserve context for long conversations with LLMs. You configure external MCP servers, optionally add internal Go-based tools, and expose a compact meta-tool interface that lets your LLM search for and execute the exact tools it needs.

How to use

You interact with OneMCP through an MCP client. Start a compatible MCP server, then connect your MCP client to the aggregator. Use the two meta-tools exposed by the aggregator to discover available tools and execute them: search for tools that match your intent, fetch detailed schemas for the tools you plan to use, and then run the chosen tools with validated arguments. This approach minimizes token usage by keeping your LLM focused on high-level goals and delegating concrete actions to the underlying tools.

How to install

Prerequisites: you need a Go toolchain to build the aggregator and Node.js for the external MCP servers you plan to run via stdio transport.

# Install Go (if not already installed)
# Follow your OS package manager instructions to install Go 1.20+ or newer
# Example for macOS with Homebrew:
# brew install go

# Install Node.js (for external MCP servers if using npm/npx based servers)
# Visit https://nodejs.org/ and install the latest LTS release

# Build the OneMCP aggregator
GOOS=darwin GOARCH=amd64 go build -o one-mcp ./cmd/one-mcp

# Build for Linux (example)
GOOS=linux GOARCH=amd64 go build -o one-mcp-linux ./cmd/one-mcp

# Run the aggregator using a configuration file
# Start with a default local config named .onemcp.json in the current directory
./one-mcp

# Or specify a custom config path
ONEMCP_CONFIG=/path/to/config.json ./one-mcp

Configure the aggregator

Create a configuration file named .onemcp.json in your project directory. The configuration below demonstrates how to load two external MCP servers using the stdio transport (command-based execution) with no extra environment variables.

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  },
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "category": "browser",
      "enabled": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "category": "filesystem",
      "enabled": true
    }
  }
}

Run and connect to the aggregator

Start the aggregator so it loads the configuration and starts serving tools to MCP clients.

# Start OneMCP aggregator (uses .onemcp.json by default)
./one-mcp

# Use a custom config file
ONEMCP_CONFIG=/path/to/config.json ./one-mcp

# Or with a specific server name/version
MCP_SERVER_NAME=my-aggregator MCP_SERVER_VERSION=0.2.0 ./one-mcp

# Enable debug logging
MCP_LOG_LEVEL=debug ./one-mcp

Additional content

Security: ensure you run the aggregator in a trusted environment and limit access to the HTTP endpoints or the stdio interfaces as appropriate for your deployment. If you expose the HTTP transport, apply proper authentication and network controls to prevent unauthorized tool execution.

Notes on configuration and tools: external servers are prefixed in tool names to avoid conflicts (for example, tools from the playwright server appear as playwright_browser_navigate). You can mix external servers and internal tools (Go-based custom tools) if you need deeper integration. Use the tool search and tool execute APIs to discover and run tools in a controlled, step-by-step fashion.

Troubleshooting

External server fails to start. Check that the command path is correct in the configuration, verify any required environment variables, and inspect the log file specified by MCP_LOG_FILE for startup errors. You can test the server command manually to confirm it launches as expected.

Tool not found. Use tool_search to verify the tool exists and confirm the server prefix is included in the tool name (e.g., playwright_browser_navigate). Ensure the external server is enabled in the configuration.

Tool execution fails. Use tool_search with detail_level set to full_schema to inspect the required arguments, verify argument types, and review logs for more detailed error messages.

Notes on tools and architecture

OneMCP aggregates tools from multiple external MCP servers and can also include internal Go-based tools. It exposes a compact meta-tool surface to reduce token usage and enable progressive discovery. Tools from external servers are automatically prefixed to prevent naming collisions, and schemas are inferred from type-safe Go structures when internal tools are used.

License and contributions

MIT License. Contributions are welcome. You can open issues or submit pull requests to improve the aggregator and its tooling integration.

Available tools

playwright_browser_navigate

Navigate to a URL within the Playwright MCP server toolset

playwright_browser_take_screenshot

Capture a screenshot of the current page using Playwright tools

filesystem_list_directory

List files in a directory using the filesystem MCP tools