Agent

What 1mcp/agent MCP server does

The 1mcp/agent MCP server puts multiple MCP backends behind one aggregated runtime. Instead of configuring every upstream server separately in each client, operators can register them with 1MCP and expose the resulting inventory through a single serve process.

The runtime supports static servers loaded from startup configuration and template servers created after client or session context becomes available. It can also combine instructions from the configured servers, apply presets and filters, and send preset change notifications.

For agent-style use, the 1mcp/agent MCP server provides a narrower command workflow than exposing every backend tool at once. Agents can request runtime instructions, inspect a server or an individual tool, and invoke a tool after examining its schema.

How it works

Start the runtime with 1mcp serve. Clients can then connect in several ways:

• CLI mode uses instructions, inspect, and run for progressive discovery.
• 1mcp proxy provides a stdio-compatible path while retaining project context and template-server support.
• Native MCP clients can connect to the runtime over streamable HTTP.

The runtime may use asynchronous loading to make the HTTP listener available earlier when a client can reconcile capability changes. Lazy loading is optional and presents a stable discovery surface based on tool_list, tool_schema, and tool_invoke. It reduces the initial schema payload, but does not reduce backend connections or processes.

Setup and configuration

Install the package globally with npm, add upstream servers through the 1MCP CLI, and start the runtime:

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

CLI mode can then be configured for supported agent workflows with commands such as 1mcp cli-setup --codex or 1mcp cli-setup --claude --scope repo --repo-root .. A project can use .1mcprc when the proxy path needs project-specific context. The README also points to configuration, authentication, and architecture documentation for runtime operators, but does not specify credential names or authentication settings in the provided material.

Tools and capabilities

• Aggregate many MCP servers behind one runtime.
• Discover instructions, server details, and tool schemas progressively.
• Invoke a selected upstream tool through CLI mode.
• Resolve template servers using client or session context.
• Apply presets and filters across the shared server inventory.
• Optionally recover owned stdio backends and expose health or status information.
• Serve native HTTP clients or stdio-compatible clients through the documented paths.

Limitations and notes

CLI mode requires an already running 1mcp serve instance. The stdio proxy also depends on that runtime, while direct HTTP attachment does not provide project context or .1mcprc handling and exposes a broader tool surface directly.

Lazy loading is opt-in and is intended to reduce initial schemas rather than backend resource usage. The README notes that it does not repair orphaned proxy processes. Direct stdio mode is described mainly as a debugging option because startup is slower than a thin standalone stdio setup.

For a given agent, the documentation recommends choosing one connection mode and removing an older direct MCP configuration before switching that agent to CLI mode.