Agent

What 1mcp/agent does

1mcp/agent provides one aggregated runtime for multiple MCP servers. The 1mcp serve command sits between clients or agents and the configured upstream servers, allowing a single runtime to manage their connections and expose a unified interface.

The package supports three access patterns. CLI mode is intended for agent-style workflows, 1mcp proxy provides a stdio-compatible bridge for clients that expect that transport, and direct streamable HTTP lets MCP-native clients connect to the running runtime. These modes can use the same server configuration while presenting different levels of discovery and project context.

How it works

Static servers are prepared from startup configuration. Template servers can instead be created after client or session information is available, which supports per-client and per-session resolution. The runtime can also use asynchronous loading to make its HTTP listener available earlier when clients can handle capability changes.

CLI mode narrows the agent-facing workflow to three steps: retrieve runtime guidance with 1mcp instructions, inspect a server or a specific tool with 1mcp inspect, then invoke the selected tool through 1mcp run. This lets an agent discover a relevant schema instead of receiving every upstream tool definition at the beginning of a session.

Optional lazy loading presents a stable backend surface based on tool_list, tool_schema, and tool_invoke. It reduces the initial schema payload but does not reduce backend connections or processes, and it does not fix orphaned proxy processes.

Setup and configuration

Install the package globally with npm, register an upstream server, and start the runtime:

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

Configure an agent for CLI mode from another shell. For Codex, use 1mcp cli-setup --codex; for Claude, use 1mcp cli-setup --claude --scope repo --repo-root .. Keep the serve process running while the agent uses CLI mode.

A project can also be selected explicitly when working across repositories or worktrees:

1mcp inspect codegraph --project /absolute/checkout

For direct HTTP attachment, point an MCP client at the running endpoint, optionally identifying the client with the app query parameter:

{
  "mcpServers": {
    "1mcp": {
      "url": "http://127.0.0.1:3050/mcp?app=cursor"
    }
  }
}

Tools and capabilities

• Aggregate multiple MCP servers behind one serve process.
• Discover runtime guidance with 1mcp instructions.
• Inspect an upstream server or individual tool with 1mcp inspect <server> and 1mcp inspect <server>/<tool>.
• Invoke a selected tool with 1mcp run <server>/<tool> --args '<json>'.
• Resolve template servers from client or session context.
• Use presets, filters, and aggregated instructions across clients and projects.
• Connect through CLI mode, the stdio proxy, or streamable HTTP.

Limitations and notes

CLI mode and the stdio proxy depend on a running 1mcp serve instance. Direct streamable HTTP is intended for clients that already speak MCP natively, but it does not provide project context or .1mcprc handling and exposes a broader tool surface directly.

Use one connection mode per agent. When moving an agent to CLI mode, remove its previous direct MCP configuration. Lazy loading is opt-in and changes how schemas are surfaced; it does not eliminate upstream processes or connections. Clients must be able to reconcile capability changes to benefit from asynchronous loading.