Skip to content
Back to search

agent

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/1mcp-app/agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/1mcp-app/agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/1mcp-app--agent/badge.svg)](/listings/1mcp-app--agent)

HTML

<a href="/listings/1mcp-app--agent"><img src="/api/listings/1mcp-app--agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 .

Then verify the agent workflow:

# 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](https://docs.1mcp.app/guide/quick-start).

For a given agent, choose one mode only. If you switch that agent to CLI mode, remove its old direct MCP configuration first.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 186 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 1MCP
  2. [![NPM Version](https://img.shields.io/npm/v/@1mcp/agent)](https://www.npmjs.com/package/@1mcp/agent)
  3. [![NPM Downloads](https://img.shields.io/npm/dm/%401mcp%252Fagent)](https://www.npmjs.com/package/@1mcp/agent)
  4. [![CodeQl](https://github.com/1mcp-app/agent/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/1mcp-app/agent/actions/workflows/github-code-scanning/codeql)
  5. [![GitHub Repo stars](https://img.shields.io/github/stars/1mcp-app/agent)](https://github.com/1mcp-app/agent/stargazers)
  6. [![Docs](https://img.shields.io/badge/docs-docs.1mcp.app-blue)](https://docs.1mcp.app)
  7. [![DeepWiki](https://img.shields.io/badge/DeepWiki-AI%20Docs-purple.svg?logo=gitbook&logoColor=white)](https://deepwiki.com/1mcp-app/agent)
  8. [![License](https://img.shields.io/npm/l/@1mcp/agent)](https://www.npmjs.com/package/@1mcp/agent)
  9. 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.
  10. ## Why 1MCP
  11. Most MCP setups eventually hit two kinds of sprawl:
  12. - Configuration sprawl: every client needs its own MCP wiring, auth choices, and filtering rules.
  13. - Agent sprawl: autonomous sessions carry too many tools and schemas into context up front.
  14. 1MCP addresses both:
  15. - `1mcp serve` gives you one aggregated runtime in front of many MCP servers.
  16. - CLI mode lets agents discover tools progressively with `instructions`, `inspect`, and `run`.
  17. - Static servers can load at startup, while template servers are created from per-client or per-session context.
  18. - Presets, filters, and instruction aggregation keep the same runtime adaptable across clients and projects.
  19. | Approach | Best for | Tradeoff |
  20. | ---------------------- | ------------------------------------ | -------------------------------------------------------------------------------- |
  21. | 1MCP CLI mode | Codex, Claude, agent loops | Requires a running `1mcp serve` instance |
  22. | 1MCP stdio proxy | Maximum compatibility across clients | Still depends on `serve`, and auth-capable HTTP clients have a more direct path |
  23. | Direct streamable HTTP | MCP-native HTTP clients | No project context, no `.1mcprc`, and a broader tool surface is exposed directly |
  24. | Custom proxying | One-off compatibility shims | You own discovery, filtering, auth, and runtime lifecycle |
  25. ## Quick Start for Agent Users
  26. 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.
  27. **You — setup:** install 1MCP, add one upstream server, and start the runtime:
  28. ```bash
  29. npm install -g @1mcp/agent
  30. 1mcp mcp add context7 -- npx -y @upstash/context7-mcp
  31. 1mcp serve
  32. ```
  33. **You — client setup:** in a second shell, connect your agent to CLI mode:
  34. ```bash
  35. 1mcp cli-setup --codex
  36. # or
  37. 1mcp cli-setup --claude --scope repo --repo-root .
  38. ```
  39. **AI agent — after startup:** follow this workflow, skipping `instructions` if hooks already delivered the current instructions. Keep the runtime above running; you do not need to repeat these agent commands manually. Verify that startup delivers guidance and establishes session ownership. With a named or implicitly discovered local runtime, supported Codex sessions resolve their owner and assigned project automatically. Claude and hosts without automatic owner lookup add their own bootstrap `--project-owner <own-file>` to the commands below; each worker uses its own credential.
  40. ```bash
  41. # Only if current target guidance is missing or needs refreshing:
  42. 1mcp instructions
  43. 1mcp inspect context7
  44. 1mcp inspect context7/query-docs
  45. 1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'
  46. ```
  47. If you want the full walkthrough (with success criteria and off-ramps), use the [Quick Start guide](https://docs.1mcp.app/guide/quick-start).
  48. For a given agent, choose one mode only. If you switch that agent to CLI mode, remove its old direct MCP configuration first.
  49. ## Privacy and Product Usage Telemetry
  50. Product Usage Telemetry is **enabled by default** outside CI and tests, with a notice before first collection. It sends aggregate command/feature counts and coarse platform information with a random, pseudonymous installation ID to 1MCP's first-party collector. It excludes prompts, tool arguments/results, credentials, paths, and arbitrary server/tool names.
  51. To opt out for your local OS-user installation, run `1mcp telemetry disable`; use `1mcp telemetry status` to check the effective policy. `DO_NOT_TRACK=1` also suppresses collection. Remote runtimes follow their owner's settings.
  52. Read [Privacy and Product Usage Telemetry](https://docs.1mcp.app/guide/privacy) ([中文](https://docs.1mcp.app/zh/guide/privacy)) for the complete data scope, local storage, retention policy, and reset limitations.
  53. ## Work Across Projects and Worktrees
  54. Use one local runtime across repositories and Git worktrees. After configuring an installed backend with `mcp setup`, the agent selects a checkout on each call:
  55. ```bash
  56. 1mcp inspect codegraph --project /absolute/checkout
  57. ```
  58. For the session’s assigned checkout, omit `--project`; explicit overrides do not change that default. Follow [Working Across Projects and Worktrees](https://docs.1mcp.app/guide/worktrees-and-cross-project-sessions) ([中文](https://docs.1mcp.app/zh/guide/worktrees-and-cross-project-sessions)) for setup, project sets, independent workers, optional preparation, and safe cleanup.
  59. ## Why CLI Mode Exists
  60. 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:
  61. - `instructions` explains the current runtime and recommended flow
  62. - `inspect` lets the agent discover only the server or tool it needs
  63. - `run` executes one selected tool after schema inspection
  64. That gives agent loops a smaller working surface without giving up the unified runtime behind `1mcp serve`.
  65. ## Choose Another Path
  66. ### Stdio Proxy
  67. Use [`1mcp proxy`](https://docs.1mcp.app/commands/proxy) when you want the broadest client compatibility without giving up project context.
  68. It is the recommended fallback after CLI mode because it:
  69. - works with the stdio transport that most AI clients already support
  70. - keeps project context through `.1mcprc`
  71. - supports template MCP servers resolved from project or session context
  72. - is easier to roll out with one-time global setup plus per-project config
  73. 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.
  74. ### Direct MCP Attachment
  75. Direct MCP attachment is still supported for clients that want to talk to the aggregated runtime over streamable HTTP.
  76. Examples:
  77. ```json
  78. {
  79. "mcpServers": {
  80. "1mcp": {
  81. "url": "http://127.0.0.1:3050/mcp?app=cursor"
  82. }
  83. }
  84. }
  85. ```
  86. ```bash
  87. claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"
  88. ```
  89. 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.
  90. ### Runtime Operators
  91. Use the deeper docs if you are configuring or deploying the runtime itself:
  92. - [Configuration](https://docs.1mcp.app/guide/essentials/configuration)
  93. - [Authentication](https://docs.1mcp.app/guide/advanced/authentication)
  94. - [Architecture](https://docs.1mcp.app/reference/architecture)
  95. ### Contributors
  96. - [Development guide](https://docs.1mcp.app/guide/development)
  97. - [CONTRIBUTING.md](CONTRIBUTING.md)
  98. ## How It Works
  99. ```mermaid
  100. flowchart LR
  101. A[User or Agent] --> B[1mcp serve]
  102. B --> C[Static servers loaded at startup]
  103. B --> D[Template servers resolved from client or session context]
  104. A --> E[CLI mode: instructions -> inspect -> run]
  105. E --> B
  106. F[Direct streamable HTTP client] --> B
  107. G[stdio-compatible client] --> H[1mcp proxy]
  108. H --> B
  109. ```
  110. 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.
  111. 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 [#392](https://github.com/1mcp-app/agent/issues/392) for the async late-server visibility contract.
  112. ## Core Capabilities
  113. - Unified runtime for many MCP servers behind one `serve` process
  114. - CLI mode for progressive discovery with `1mcp instructions`, `1mcp inspect <server>`, `1mcp inspect <server>/<tool>`, and `1mcp run <server>/<tool> --args '<json>'`
  115. - Template servers for per-client or per-session resolution
  116. - Opt-in async loading for early HTTP listener availability when clients can reconcile capability changes
  117. - Opt-in lazy loading for a stable progressive-discovery tool surface and smaller initial schemas
  118. - Opt-in automatic recovery for owned stdio backends, with health/status visibility and operator restart controls
  119. - Instruction aggregation across static and template-backed servers
  120. - Presets, filters, and preset change notifications
  121. - `proxy` for maximum compatibility with project context and template-server support
  122. - Direct streamable HTTP MCP access for native HTTP clients that do not need project context
  123. ## Common Use Cases
  124. - Give a coding agent one stable runtime but a smaller working surface.
  125. - Share the same MCP inventory across Cursor, Claude Code, Codex, and internal tooling.
  126. - Expose context-specific template servers per repo, branch, or session.
  127. - Centralize auth, filtering, presets, and runtime lifecycle instead of rebuilding them in ad hoc scripts.
  128. ## Contributing / License
  129. Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and [LICENSE](LICENSE) for the Apache 2.0 license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.