DOCSEARCHbyAlgolia
Submit Docs

1MCP Documentation

repository·main·Indexed 19 days ago

https://github.com/1mcp-app/agent

Documentation for @1mcp/agent (v0.35.0-beta.3), a unified Model Context Protocol (MCP) server implementation designed to aggregate multiple MCP servers. It features an Aggregated Runtime for managing server lifecycles, a browser-based Admin Console for observation, and a CLI for administration. Key capabilities include backend stdio supervision, tool description overrides, instruction templates, and a capability catalog for tool and resource discovery.

Tokens
153K
Snippets
445
Records
678
Agent score
66%

What's inside 1MCP

  3. Overview of 1MCP Core Features

    main

    1MCP provides essential capabilities for aggregating and managing Model Context Protocol (MCP) servers. Core features include:

    • Universal MCP Aggregation: Connect multiple MCP servers through a single unified endpoint.
    • Hot Configuration Reload: Add or remove servers instantly without system downtime.
    • Basic Status Monitoring: Track active connections and troubleshoot connectivity issues.
    • Fast Startup: Uses asynchronous background loading to ensure 1MCP is ready in under 1 second, regardless of the number of configured servers.

  4. Manage MCP server lifecycle with installation tools

    main

    The 1MCP ecosystem provides a suite of internal tools designed for AI assistants to manage the complete lifecycle of MCP servers. These tools allow for automated installation, removal, and version management.

    Core Tools

    • mcp_install: Installs MCP servers from registries, Git repositories, or custom URLs. It supports version specification, dependency resolution, and automatic configuration.
    • mcp_uninstall: Safely removes MCP servers. It includes dependency checking, backup options, and resource cleanup to ensure no side effects on other servers.
    • mcp_update: Updates servers to newer versions. It handles compatibility checking, dependency updates, and provides rollback capabilities if an update fails.

    Typical Installation Workflow

    1. Discovery: Find a suitable server using discovery tools.
    2. Installation: Execute mcp_install specifying the source and version.
    3. Verification: Use management tools to confirm the server is running correctly.
    4. Configuration: Apply settings and enable the server for use.

  5. Manage desktop application MCP configurations with the `app` command group

    main

    The app command group allows you to consolidate MCP (Model Context Protocol) server configurations from various desktop applications into a unified 1MCP proxy. This workflow helps centralize management of MCP servers across different tools like Claude Desktop, Cursor, and VS Code.

    For a detailed workflow and best practices, refer to the App Consolidation Guide.

  6. What is 1MCP CLI Mode

    main

    CLI Mode is a progressive tool access workflow designed specifically for AI agents (like Codex or Claude). Instead of exposing a massive, high-context list of all available MCP tools directly into the agent's prompt, CLI Mode allows the agent to discover and use tools incrementally.

    Key Benefits:

    • Token Efficiency: Reduces prompt size by only showing tool schemas when needed.
    • Progressive Disclosure: The agent follows a workflow of: Inventory $\rightarrow$ Server Inspection $\rightarrow$ Tool Inspection $\rightarrow$ Execution.
    • Reduced Noise: Prevents large tool catalogs and verbose schemas from cluttering long-running agent sessions.

    Important Constraint: You must choose only one mode per agent. If you switch an agent to CLI Mode, you must remove its existing direct MCP server configuration first.

  7. Overview of MCP Internal Tools

    main

    MCP internal tools are Model Context Protocol (MCP) tools designed specifically for AI assistant integration and automated workflows. Unlike CLI commands intended for humans, these tools allow AI assistants to programmatically discover, install, manage, and interact with MCP servers via the MCP protocol.

    The tools are categorized into three functional domains:

    1. Discovery Tools: Used to search registries and discover available MCP servers.
    2. Installation Tools: Used to install, update, and remove MCP servers.
    3. Management Tools: Used to control server operational state, configuration, and health.

    AI assistants can use these tools to automate environment setup, monitor server health, and orchestrate complex workflows involving multiple servers. Developers can also integrate them into CI/CD pipelines or Infrastructure as Code (IaC) solutions.

  8. Select the correct Serena context

    main

    Serena uses a context system to provide different tool sets optimized for specific client types. Match your client to the recommended context:

    Client TypeRecommended Context
    Claude Code CLIclaude-code
    Cursor, VSCodeide
    Codex CLIcodex
    Custom agentCreate custom context

    Custom contexts can be defined in ~/.serena/serena_config.yml.

  9. Target Verification and Identity Safety

    main

    To prevent credential leakage, target setup and verification follow a strict security protocol:

    1. Low-Disclosure Identity Check: The CLI uses a low-disclosure Runtime Identity endpoint (not /admin/api) to verify the target.
    2. Identity Binding: A stored target is bound to an observed runtimeScopeId. If the observed identity does not match the stored identity, the operation fails closed before any credentials are sent.
    3. Credential Clearing: If you perform an identity replacement, the stored OAuth and Admin credentials for that target are cleared.

  10. The 1MCP CLI workflow resulting from cli-setup

    main

    Once cli-setup is configured, the managed startup docs instruct the agent to follow this specific execution order:

    1. Initialize: Run 1mcp instructions (unless the session already received instructions via hooks).
    2. Discover Server: Run 1mcp inspect <server> before selecting a tool.
    3. Discover Tool: Run 1mcp inspect <server>/<tool> before invocation.
    4. Execute: Run 1mcp run <server>/<tool> --args '<json>' only after the tool schema has been inspected.

  11. Understand OAuth Refresh Token Rotation and Replay Protection

    main

    1MCP implements a strict OAuth 2.0 refresh token rotation strategy using Rotating Families. This mechanism is designed to protect public PKCE clients from token replay attacks.

    Key Behaviors:

    • Token Families: Each approved authorization creates an independent Refresh Token Family that is bound to a specific client, resource, and scope. Families persist in their Runtime Scope for 30 days.
    • Single-Use Tokens: Every successful refresh operation rotates the token. The old token is consumed and replaced by a new single-use opaque token. Only token digests and family lineage are stored.
    • Replay Detection & Revocation: Because public PKCE clients are not sender-constrained, reusing any consumed member of a family triggers immediate revocation. If a token is reused, the entire family and all access tokens issued from it are revoked.
    • No Retry Grace Period: There is no grace period for concurrent refreshes. Only one refresh attempt can succeed; any subsequent or concurrent attempt using the same token is treated as a replay attack.
    • Scope Narrowing: A refresh operation may result in a new access token with narrower scopes than the previous one.
    • Access Token Lifecycle: Revoking or rotating a refresh token does not automatically revoke existing access tokens; they remain valid until their own individual expiry. Explicit revocation must be handled locally per token.

    Developer Impact:

    If a client experiences a lost response or a network failure during a refresh, the client may be forced to perform a full reauthorization, as the runtime does not permit two valid successors or extend the family lifetime beyond the original 30 days.

  12. Use XML Tags for Server Instructions

    main

    To improve LLM routing and understanding, wrap server-specific instructions in XML-like tags where the tag name matches the server name.

    Format: <server-name>instructions content</server-name>

    Benefits:

    • Provides clear boundaries between different server capabilities.
    • Helps LLMs identify exactly which server provides which instructions.
    • Renders cleanly in 1MCP due to noEscape: true configuration.