# 1mcp/agent [Health: Active]

**Category:** 🔗 Aggregators  
**Repository:** https://github.com/1mcp-app/agent  
**GitHub Stars:** 524  
**Views:** 14  
**Installs:** 1  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/1mcp-agent

## Description
A unified Model Context Protocol server implementation that aggregates multiple MCP servers into one.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent": {
    "command": "npx",
    "args": ["-y","@1mcp/agent"]
  }
}
```

## Documentation

## 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:

```bash
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:

```bash
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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/1mcp-agent/readme_