agent

The 1MCP Agent is a unified MCP server that aggregates multiple MCP servers into a single entry point. It runs as a proxy and orchestrator: it starts and stops configured MCP backend servers as subprocesses, forwards incoming requests from AI assistants to the correct backend, and exposes a single API surface for clients. This makes it easy to manage diverse MCP implementations (for example context providers, file systems, or experimental MCPs) through one central server. You can add or remove backend MCP servers in the configuration and rely on hot-reload capabilities to apply changes without restarting the entire stack. You can then connect your assistants (like Cursor, VSCode, Claude Code, etc.) to the agent's public endpoint and have requests routed to the appropriate backend MCP server.

To use it, install or run the agent, then configure the internal MCP server list that you want to aggregate. Once running, you interact with the single /mcp endpoint exposed by the agent and let it handle dispatching to the underlying MCP servers. The included documentation covers installation, configuration, authentication, and deployment considerations, so you can tailor security (OAuth 2.1), health checks, and logging to your environment.

Prerequisites:

• Node.js and npm or a binary distribution as described below
• Internet access to fetch the agent package

Option A: Binary (Recommended – No Node.js Required)

• Linux/macOS: curl -L https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64.tar.gz | tar -xz sudo mv 1mcp /usr/local/bin/
• Windows (PowerShell): Invoke-WebRequest -Uri "https://github.com/1mcp-app/agent/releases/latest/download/1mcp-win32-x64.zip" -OutFile "1mcp.zip" Expand-Archive -Path "1mcp.zip" -DestinationPath "."

Option B: NPM (Node.js required for npm-based installation)

• Install and run via NPX (no global install required): npx -y @1mcp/agent --help

Option C: Run via Node.js (if you prefer running the server script directly)

• Ensure you have Node.js installed
• Install the package and run the server entry point as per your project setup

Basic run example (via NPX):

• npx -y @1mcp/agent

Configuration:

• After starting, configure the MCP backend servers you want to aggregate (see documentation) and optionally enable hot-reload for dynamic updates.

Tips and common issues:

• Environment variables: you can configure authentication, logging, and health checks via environment variables as described in the docs. For example, set OAUTH2 settings, MESSAGING transports, and log levels as needed.
• Hot-reload: the agent supports hot-reload of its configuration. If you add or remove backend MCP servers, the agent can reload the configuration without a full restart.
• Health endpoints: use the built-in health check endpoints to monitor the status of the aggregated MCP servers.
• Networking: ensure that the agent can reach all configured MCP servers and that firewall rules allow the necessary traffic.
• Compatibility: the agent aggregates multiple MCP servers; ensure backend servers use compatible MCP interfaces and authorization scopes if OAuth is used.
• Troubleshooting: check logs for errors related to starting/stopping backend MCP processes, subprocess exit codes, and network routing decisions.