1MCP: One Aggregated MCP Runtime in Front of Many MCP Servers
A unified Model Context Protocol server implementation that aggregates multiple MCP servers into one.
At a glance
- What is it?
- 1MCP (the @1mcp/agent package) puts a single runtime in front of multiple Model Context Protocol servers, then offers agents a thinner instructions, inspect, run workflow. Here is what it actually does, how to start it, and where it stops being the right tool.
- Who is it for?
- Adopt 1MCP if you run several MCP servers across more than one agent and want one aggregated runtime plus a progressive instructions, inspect, run workflow. Do not adopt it if you need one thin stdio server with no extra hop, or if you cannot keep a 1mcp serve process alive.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The Two Kinds of Sprawl 1MCP Is Aimed At
The README names two problems. Configuration sprawl: every client needs its own MCP wiring, auth choices and filtering rules. Agent sprawl: autonomous sessions carry too many tools and schemas into context up front. 1MCP is for people running several MCP servers across Codex, Claude, Cursor or similar tool-using agents, and who are tired of duplicating that wiring per client. It is not aimed at someone with a single MCP server and a single client, because the runtime adds a process and a hop that a thin standalone stdio setup does not have. The project describes itself as the unified MCP runtime, with 1mcp serve as the aggregation point and CLI mode as the agent-facing workflow.
How 1mcp serve Aggregates Static and Template Servers
The architecture diagram in the README shows a user or agent connecting to 1mcp serve, which then fronts two categories of upstream server. Static servers are prepared from startup configuration. Template servers are materialized when client context is known, which is how per-client or per-session servers get resolved. The same runtime is reachable three ways: CLI mode through instructions, inspect and run; a stdio-compatible client through 1mcp proxy; and a direct streamable HTTP client hitting the runtime itself. The README also describes async loading, which makes the HTTP listener available early, and lazy loading, an opt-in compatibility mode that keeps the backend discovery and invocation surface at tool_list, tool_schema and tool_invoke so capable agents can discover tools progressively without replacing their MCP tool table. That is a real trade-off worth stating: lazy loading reduces the initial schema payload, but the README says it does not reduce backend connections or processes.
Installing 1MCP and Running a First Tool
The README's quick start installs the package globally, registers one upstream server, and starts the runtime. The context7 example uses npx to pull the upstream server on demand.
npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serveWith the runtime running, the second shell connects an agent to CLI mode. The README shows a Codex variant and a Claude variant scoped to a repository.
1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .The agent workflow is then three commands. instructions explains the current runtime and recommended flow, inspect discovers one server or one tool, and run executes a selected tool after its schema has been inspected.
1mcp instructions
1mcp inspect context7
1mcp inspect context7/query-docs
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'For clients that speak MCP natively over streamable HTTP, the README gives a JSON attachment pointing at port 3050, and a Claude CLI equivalent.
claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"The README warns to choose one mode per agent, and to remove that agent's old direct MCP configuration before switching it to CLI mode.
Where 1MCP Is the Wrong Tool
Startup cost is the first constraint. The README states plainly that direct stdio mode is not the recommended path and is mainly useful for debugging, because 1MCP startup is slower than a thin standalone stdio setup. If your client only speaks stdio and you want the smallest possible process tree, the extra runtime is a cost you pay for aggregation you may not need. The second constraint is a dependency: CLI mode requires a running 1mcp serve instance, and the stdio proxy also depends on serve. A single-user desktop setup where the agent launches the server itself now has a long-lived process to keep alive. Third, direct streamable HTTP attachment gives up project context and .1mcprc, and exposes a broader tool surface directly, which is the opposite of what CLI mode is trying to achieve. The README frames that path as suitable only when the client already speaks MCP natively, can work without project context, and you do not want CLI mode.
1MCP Proxy Versus a Hand-Written Compatibility Shim
The README's comparison table lists custom proxying as the alternative for one-off compatibility shims, with the tradeoff that you own discovery, filtering, auth and runtime lifecycle. That is the honest difference. A hand-written shim can be exactly as thin as one client needs, and you control every byte on the wire. 1MCP instead ships presets, filters, instruction aggregation, template servers resolved from project or session context, and notifications as part of the runtime. The proxy path is positioned as the recommended fallback after CLI mode: it works with the stdio transport most AI clients already support, keeps project context through .1mcprc, and is easier to roll out with one-time global setup plus per-project config. Choosing between them is really a question of whether you want to maintain that layer yourself.
Deployment, Licence and Upgrade Surface
The repository ships a Dockerfile and a docker-compose.yml. The compose file runs ghcr.io/1mcp-app/agent:latest, publishes port 3050, mounts ~/.config/1mcp/ into the container, and sets ONE_MCP_HOST, ONE_MCP_PORT and ONE_MCP_EXTERNAL_URL. The Dockerfile builds with pnpm --frozen-lockfile and exposes 3050, with an extended stage that adds uv and bun for servers that need Python or Bun tooling. Configuration keys visible in .env.example include ONE_MCP_LOG_LEVEL, ONE_MCP_LOG_FILE, ONE_MCP_CONFIG, ONE_MCP_PORT, ONE_MCP_ENABLE_AUTH and ONE_MCP_ENABLE_ASYNC_LOADING. The package is published on npm as @1mcp/agent, and package.json declares Apache-2.0. Note the version gap: package.json reads 0.38.0 while the most recent release listed is v0.37.0, so the npm artifact and the release notes can move independently. Releases have been frequent, with v0.35.0, v0.36.0 and v0.37.0 all landing in August 2026, and the last push to main was on 2026-09-10. That cadence cuts both ways: fixes arrive quickly, and so do config or CLI changes you may have to absorb. The Apache-2.0 licence permits commercial use and modification, but it also means no vendor support obligation; check the LICENSE file and any dependency licences yourself rather than treating this paragraph as legal advice.
Editorial conclusion
Adopt 1MCP if you run several MCP servers across more than one agent and want one aggregated runtime plus a progressive instructions, inspect, run workflow. Do not adopt it if you need one thin stdio server with no extra hop, or if you cannot keep a 1mcp serve process alive. Before committing, verify that CLI mode is the right path for each agent and remove any old direct MCP configuration for that agent, since the README says to choose one mode only.
Frequently asked questions
What is 1MCP and what problem does it solve?
1MCP is a unified MCP runtime that aggregates multiple MCP servers behind a single 1mcp serve instance. The README frames it as a fix for configuration sprawl, where every client needs its own MCP wiring, and agent sprawl, where sessions carry too many tools and schemas up front.
How do I install 1MCP?
The README's quick start installs it globally with npm install -g @1mcp/agent, adds an upstream server with 1mcp mcp add, and starts the runtime with 1mcp serve. A Docker Compose file is also provided, running ghcr.io/1mcp-app/agent:latest on port 3050.
What is the difference between 1MCP CLI mode and the stdio proxy?
CLI mode is the primary workflow for agent-style sessions and narrows what the agent sees through instructions, inspect and run. The stdio proxy is the recommended fallback for broader client compatibility, works with the stdio transport most AI clients support, and keeps project context through .1mcprc.
Does 1MCP lazy loading reduce backend connections?
No. The README states that lazy loading reduces the initial schema payload but does not reduce backend connections or processes. It is an opt-in stable tool-surface compatibility mode that keeps the discovery and invocation surface at tool_list, tool_schema and tool_invoke.
What port does 1MCP listen on?
The Docker Compose file and the Dockerfile both use port 3050, and the direct HTTP attachment example points at http://127.0.0.1:3050/mcp. The .env.example file shows ONE_MCP_PORT set to 3051, so the port is configurable.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/1mcp-app-agent)