1mcp/agent

1MCP is the unified MCP runtime. 1mcp serve aggregates your MCP servers, and CLI mode adds a thinner agent-facing workflow for Codex, Claude, Cursor, and similar tool-using agents.
Why 1MCP
Most MCP setups eventually hit two kinds of sprawl:
- 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 addresses both:
- 1mcp serve gives you one aggregated runtime in front of many MCP servers.
- CLI mode lets agents discover tools progressively with instructions, inspect, and run.
- Static servers can load at startup, while template servers are created from per-client or per-session context.
- Presets, filters, and instruction aggregation keep the same runtime adaptable across clients and projects.
| Approach | Best for | Tradeoff |
| ---------------------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| 1MCP CLI mode | Codex, Claude, agent loops | Requires a running 1mcp serve instance |
| 1MCP stdio proxy | Maximum compatibility across clients | Still depends on serve, and auth-capable HTTP clients have a more direct path |
| Direct streamable HTTP | MCP-native HTTP clients | No project context, no .1mcprc, and a broader tool surface is exposed directly |
| Custom proxying | One-off compatibility shims | You own discovery, filtering, auth, and runtime lifecycle |
Quick Start for Agent Users
This page is optimized for AI agent users. The 5-minute outcome is simple: start a real 1mcp serve runtime, connect your agent with cli-setup, then verify the instructions -> inspect -> run workflow.
Install 1MCP, add one upstream server, and start the runtime:
In a second shell, connect your agent to CLI mode:
Then verify the agent workflow:
If you want the full walkthrough (with success criteria and off-ramps), use the Quick Start guide.
For a given agent, choose one mode only. If you switch that agent to CLI mode, remove its old direct MCP configuration first.
Why CLI Mode Exists
CLI mode is the primary workflow for agent-style sessions. It keeps MCP as the backend protocol but narrows what the agent sees at each step:
- instructions explains the current runtime and recommended flow
- inspect lets the agent discover only the server or tool it needs
- run executes one selected tool after schema inspection
That gives agent loops a smaller working surface without giving up the unified runtime behind 1mcp serve.
Choose Another Path
Stdio Proxy
Use 1mcp proxy when you want the broadest client compatibility without giving up project context.
It is the recommended fallback after CLI mode because it:
- works with the stdio transport that most AI clients already support
- keeps project context through .1mcprc
- supports template MCP servers resolved from project or session context
- is easier to roll out with one-time global setup plus per-project config
Direct stdio mode is not the recommended path. It is mainly useful for debugging because 1MCP startup is slower than a thin standalone stdio setup.
Direct MCP Attachment
Direct MCP attachment is still supported for clients that want to talk to the aggregated runtime over streamable HTTP.