1MCP: One Aggregated MCP Runtime in Front of Many Servers

The Two Kinds of Sprawl 1MCP Targets

The README names two failure modes it was built against. Configuration sprawl: every client needs its own MCP wiring, its own auth choices, its own filtering rules. Agent sprawl: autonomous sessions carry too many tools and schemas into context up front. These are different problems that happen to share a cause, which is that MCP servers are usually wired directly into whatever client talks to them.

The audience follows from that. If you run one MCP server in one editor, this project is overhead. If you run several servers and connect them to Codex, Claude, Cursor and a few HTTP clients, the per-client duplication is real, and so is the context cost of handing an agent every tool schema at session start. The README states the intended split plainly: `1mcp serve` gives you one aggregated runtime in front of many MCP servers, and CLI mode lets agents discover tools progressively with `instructions`, `inspect`, and `run`. Those are two products in one binary, and the documentation treats them as separate adoption paths.

How the Aggregated Runtime Resolves Servers

The architecture diagram in the README shows a single `1mcp serve` process with three entry points. A user or agent talks to it directly through CLI mode. A direct streamable HTTP client hits it at a URL such as `http://127.0.0.1:3050/mcp?app=cursor`. A stdio-compatible client goes through `1mcp proxy`, which forwards into the same runtime.

Inside the runtime, servers are split into two categories. Static servers are prepared from startup configuration. Template servers are materialized when client context is known, so a per-client or per-session value can decide what gets created. The README also describes two loading behaviours: async loading for early HTTP listener availability, and lazy loading for a stable tool surface. Lazy loading is explicitly opt-in and described as a compatibility mode. It keeps the backend discovery and invocation surface at `tool_list`, `tool_schema`, and `tool_invoke` so agents can discover tools progressively without replacing their MCP tool table. The README notes it reduces the initial schema payload but does not reduce backend connections. That distinction matters: you are trading schema bytes, not server count.

CLI Mode Is the Primary Path, Not a Convenience

The README is unusually direct about mode selection: for a given agent, choose one mode only, and if you switch that agent to CLI mode, remove its old direct MCP configuration first. Running both means the agent sees the same tools through two paths.

The three commands form a sequence. `instructions` explains the current runtime and recommended flow. `inspect` lets the agent discover only the server or tool it needs, at two levels: `1mcp inspect context7` for a server, `1mcp inspect context7/query-docs` for a single tool. `run` executes one selected tool after schema inspection, with arguments passed as JSON. The README's worked example is `1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'`.

The cost is a dependency. The README's own comparison table lists the tradeoff for CLI mode as requiring a running `1mcp serve` instance. An agent that cannot reach that process has no tools at all. This is a deliberate trade of availability for context economy, and for long agent loops it is the right one. For a one-shot script that needs a single tool call, it is a worse deal than attaching directly.

Getting It Running: Install, Add, Serve, Connect

The README's quick start is four commands. Install globally with `npm install -g @1mcp/agent`. Register an upstream server with `1mcp mcp add context7 -- npx -y @upstash/context7-mcp`, which takes a name and then the command to launch the server. Start the runtime with `1mcp serve`. In a second shell, connect your agent with `1mcp cli-setup --codex`, or with `1mcp cli-setup --claude --scope repo --repo-root .` when you want the configuration scoped to a repository rather than global.

For clients that speak MCP natively over HTTP, the alternative is a JSON block pointing at `http://127.0.0.1:3050/mcp?app=cursor`, or a command form: `claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"`. The `app` query parameter is how the runtime learns which client is calling, which is what template servers resolve against. Project context comes from a `.1mcprc` file, referenced in the README's comparison table as the thing direct streamable HTTP attachment gives up. Configuration, authentication and architecture each have their own page under docs.1mcp.app; the README does not reproduce their contents, so treat those as required reading before a shared deployment.

Where 1MCP Is the Wrong Tool

The README admits one limitation without prompting: 1MCP startup is slower than a thin standalone stdio setup, and direct stdio mode is therefore not the recommended path, mainly useful for debugging. That is a real constraint for interactive clients that expect a server to be ready immediately. Async loading exists to get the HTTP listener up early, but the underlying aggregation work does not disappear.

Lazy loading carries its own boundary. It reduces the initial schema payload but not backend connections, so it does not help if your problem is that the runtime holds too many upstream servers open. And it changes the surface your agent sees to `tool_list`, `tool_schema`, and `tool_invoke`, which only works for agents capable of discovering tools progressively. An agent that expects its full tool table at session start will not adapt to that mode, which is presumably why it is opt-in rather than default.

The mode rules are another failure surface. The README warns against running an agent in both CLI mode and a direct configuration, and warns that CLI mode requires a live `serve` process. Both are configuration mistakes that produce confusing symptoms rather than clean errors.

Compared With Writing Your Own Proxy

The README's comparison table lists custom proxying as the fourth option, best for one-off compatibility shims, with the tradeoff stated as: you own discovery, filtering, auth, and runtime lifecycle. That is the honest alternative, and for some teams it is the correct one. A hand-written shim that forwards stdio to one HTTP endpoint is perhaps a hundred lines and has no release cadence to track.

The difference in approach is what you inherit. A custom proxy does not give you presets, instruction aggregation, template servers resolved from client or session context, or a lazy loading mode with a fixed discovery surface, because you would have to build each of those. It also does not give you the slower startup or the `.1mcprc` file format. The choice is between owning four subsystems and adopting a runtime that ships a new minor version roughly every one to two weeks, judging by the v0.35.0, v0.36.0 and v0.37.0 dates. That cadence is the real cost of the dependency, and it is worth weighing before you put it in front of every client you run.

Licence, Versions and What Upgrades Cost You

The project is Apache-2.0, a permissive licence that permits commercial use and modification and includes an explicit patent grant. It also imposes notice and attribution obligations on redistributed copies and modified files. That is a summary of the licence text, not legal advice; read the LICENSE file in the repository if you plan to redistribute a modified build.

The release history shows v0.37.0 on 2026-08-31, v0.36.0 on 2026-08-23 and v0.35.0 on 2026-08-18. Three minor releases in under three weeks, all still on a 0.x line. Semver gives no stability guarantee below 1.0, so a minor bump can carry a breaking change, and the repository is still receiving pushes as of 2026-09-10. There is no long-term support branch described in the material, and no migration guide referenced in the README. If you pin a version, you own the upgrade work yourself when you move off it.

The practical upgrade cost sits in three places: the `.1mcprc` format, the CLI command surface (`instructions`, `inspect`, `run`, `cli-setup`, `mcp add`, `proxy`, `serve`), and the lazy loading tool names. Any of those changing in a 0.x minor release means editing configuration across every client you connected. Teams running a single editor and a single server will not feel it. Teams that rolled 1MCP out to a dozen repositories will.

Editorial conclusion

Adopt 1MCP if you run several MCP servers across more than one client and want a single runtime plus a smaller tool surface for agent loops. Skip it if you have one server and one client, since the extra `1mcp serve` process and its slower startup buy you nothing there. Before committing, verify the authentication model in the advanced docs, confirm your client works in CLI mode or via `1mcp proxy`, and read the lazy loading section to see whether `tool_list`, `tool_schema` and `tool_invoke` fit your agent's tool table.

Official sources

1. 1mcp-app/agent on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases