1MCP Agent

1MCP Agent is a unified Model Context Protocol (MCP) runtime built with TypeScript, designed to solve the fragmentation of MCP server configurations and complex lifecycle management in multi-client environments. The project aggregates multiple upstream MCP servers behind a single 1mcp serve process, offering four access modes: a progressive CLI mode designed for AI agents (narrowing the tool surface via instructions/inspect/run), a maximum-compatibility stdio proxy mode, a native Streamable HTTP direct connection mode, and a custom proxy mode.

In terms of core aggregation capabilities, 1MCP Agent differentiates between static servers and template servers dynamically created based on project context (.1mcprc), supporting both async loading and tool-level lazy loading. The runtime features built-in cross-server instruction aggregation, switchable preset systems, and filtering mechanisms based on client or project dimensions. To meet production-grade requirements, the runtime integrates OAuth authentication, rate limiting, and tiktoken-based token statistics. The project supports Docker containerized deployment and Node.js SEA single-file binary compilation, providing comprehensive cross-platform (including ARM64) execution capabilities.

Architecture Overview#

Adopts a two-layer structure: the bottom layer is the long-lived Aggregated Runtime (1mcp serve), responsible for config loading, client routing, and backend server management; the upper layer is the CLI Progressive Proxy Interface, interacting with the runtime for tool discovery and execution.

Core components:

• Aggregated Runtime: Core long-running process managing config, routing, transport, and backend servers.
• Server Manager: Tracks outbound server connections and inbound client sessions.
• Instruction Aggregation: Merges instructions across static and template servers.
• Template Server Manager: Reads context config (.1mcprc) to dynamically instantiate MCP servers, supporting shared or isolated session scopes.
• Preset Manager: Handles tool set preset initialization and runtime change notifications.

CLI Commands#

• 1mcp serve: Start the aggregated runtime
• 1mcp proxy: Start stdio-to-HTTP proxy
• 1mcp instructions: Get current runtime status and recommended workflow
• 1mcp inspect <server>[/<tool>]: Discover servers or view tool schema
• 1mcp run <server>/<tool> --args '<json>': Execute a specific tool
• 1mcp mcp add <name> -- <cmd>: Add an upstream MCP server
• 1mcp cli-setup --codex|--claude: Quick-configure AI agent environment

Configuration Files#

• config.toml: Core config defining static servers, templates, and presets
• .1mcprc: Project-level context config for dynamic template server rendering
• .env: Environment variables and secrets
• mcp.json: MCP server connection definitions

Quick Start#

npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve

Connect an agent (in a separate terminal):

1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .

Verify workflow:

1mcp instructions
1mcp inspect context7
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'

Typical Scenarios#

• Unified tool entry for coding agents: Provide a stable runtime for Codex, Claude Code, Cursor, etc., while narrowing the work surface via CLI mode
• Multi-client MCP config sharing: Share the same MCP server list across Cursor, Claude Code, Codex, and internal tools
• Context-aware tools per repo/branch/session: Dynamically create MCP servers for different projects via template servers
• Centralized auth and lifecycle management: Unify auth, filtering, presets, and runtime lifecycle
• Team/production deployment: Support for auth, Docker deployment, rate limiting, and other ops features

Ecosystem Integration#

• Built on @modelcontextprotocol/sdk ^1.25.1, can aggregate any MCP-compatible upstream service
• Natively adapts to OpenAI Codex, Anthropic Claude Code, Cursor, and other mainstream coding agents
• Repository includes smithery.yaml for deployment integration via the Smithery platform

Current version v0.31.0 (68 releases), Apache-2.0 license, primarily TypeScript (98%), requires Node.js 18+.