1MCP

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. 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 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. 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: ``` `npm install -g @1mcp/agent 1mcp mcp add context7 -- npx -y @upstash/context7-mcp 1mcp serve` ``` In a second shell, connect your agent to CLI mode: ``` `1mcp cli-setup --codex # or 1mcp cli-setup --claude --scope repo --repo-root .` ``` ``` `# shell 1 1mcp serve # shell 2 1mcp instructions 1mcp inspect context7 1mcp inspect context7/query-docs 1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'` ``` 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. 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`. Use](https://docs.1mcp.app/guide/quick-start)[`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 is still supported for clients that want to talk to the aggregated runtime over streamable HTTP. ``` `{ "mcpServers": { "1mcp": { "url": "http://127.0.0.1:3050/mcp?app=cursor" } } }` ``` ``` `claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"` ``` Use this path if your client already speaks MCP natively, can work without project context, and you do not want CLI mode. For Codex, Claude, Cursor, and similar agent loops, prefer CLI mode first and`proxy`second. Use the deeper docs if you are configuring or deploying the runtime itself: - ](https://docs.1mcp.app/commands/proxy)[Configuration - ](https://docs.1mcp.app/guide/essentials/configuration)[Authentication - ](https://docs.1mcp.app/guide/advanced/authentication)[Architecture ``` `flowchart LR A](https://docs.1mcp.app/reference/architecture)[User or Agent] --> B[1mcp serve] B --> C[Static servers loaded at startup] B --> D[Template servers resolved from client or session context] A --> E[CLI mode: instructions -> inspect -> run] E --> B F[Direct streamable HTTP client] --> B G[stdio-compatible client] --> H[1mcp proxy] H --> B` ``` 1MCP runs as an aggregated runtime behind`1mcp serve`. Static servers are prepared from startup configuration, template servers are materialized when client context is known, and the runtime can use async loading for early HTTP listener availability and lazy loading for a stable tool surface. Instruction aggregation, presets, and notifications sit alongside that runtime rather than outside it. Lazy loading is an opt-in stable tool-surface compatibility mode. It 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. Any explicitly enabled internal management tools remain directly exposed. Lazy loading reduces the initial schema payload, but it does not reduce backend connections or processes, make synchronous startup bind earlier, or repair orphaned proxy processes. See[#392for the async late-server visibility contract. - Unified runtime for many MCP servers behind one`serve`process - CLI mode for progressive discovery with`1mcp instructions`,`1mcp inspect <server>`,`1mcp inspect <server>/<tool>`, and`1mcp run <server>/<tool> --args '<json>'` - Template servers for per-client or per-session resolution - Opt-in async loading for early HTTP listener availability when clients can reconcile capability changes - Opt-in lazy loading for a stable progressive-discovery tool surface and smaller initial schemas - Opt-in automatic recovery for owned stdio backends, with health/status visibility and operator restart controls - Instruction aggregation across static and template-backed servers - Presets, filters, and preset change notifications - `proxy`for maximum compatibility with project context and template-server support - Direct streamable HTTP MCP access for native HTTP clients that do not need project context - Give a coding agent one stable runtime but a smaller working surface. - Share the same MCP inventory across Cursor, Claude Code, Codex, and internal tooling. - Expose context-specific template servers per repo, branch, or session. - Centralize auth, filtering, presets, and runtime lifecycle instead of rebuilding them in ad hoc scripts. Contributions are welcome. See](https://github.com/1mcp-app/agent/issues/392)[CONTRIBUTING.mdfor the development workflow and](https://github.com/1mcp-app/agent/blob/HEAD/CONTRIBUTING.md)[LICENSEfor the Apache 2.0 license. This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases. Create crafted UI components inspired by the best 21st.dev design engineers. Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively . MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent ALAPI MCP Tools,Call hundreds of API interfaces via MCP AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references. APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API. One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth. Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB](https://github.com/1mcp-app/agent/blob/HEAD/LICENSE)