1MCP - Consolidated Context Protocol Endpoint

This repository details the 1MCP (One Model Context Protocol) server, a highly effective middleware solution that pools multiple independent MCP service instances into a singular, cohesive operational interface.

Index

• Synopsis
• Key Capabilities
• Rapid Deployment Guide
• Command Line Interface Reference
• Runtime Requirements
• Operational Usage
• Containerization with Docker
• Server Tagging Strategy
• Configuration Mechanics
• Security Measures (AuthN)
• System Status & Observability
• Internal Mechanics
• Contribution Guidelines
• Collaboration Policy
• Licensing Information

Synopsis

The 1MCP framework is engineered to streamline interactions with heterogeneous AI environments. It abstracts away the complexity of orchestrating separate MCP instances (e.g., those backing Claude Desktop, Cursor, Roo Code, etc.) by funneling all communication through a single, resilient server instance.

Key Capabilities

• Centralized Endpoint: Unifies access across disparate MCP backends.
• Efficiency Gains: Significantly reduces system resource consumption by consolidating redundant process management.
• Configuration Abstraction: Simplifies the maintenance of credentials and endpoints for diverse AI services.
• Protocol Standardization: Enforces a consistent interaction layer for models interfacing with external utilities.
• Hot Reloading: Permits dynamic modification of service definitions without interrupting server operation.
• Asynchronous Provisioning: Supports loading of new context servers asynchronously, updating client capabilities in real-time via change notifications.
• Robust Cleanup: Implements reliable shutdown sequences for proper resource reclamation.
• Security Hardening: Incorporates robust mechanisms for client authentication and access control.
• Performance Tuning: Offers advanced request routing, filtering, and optimization features.
• Operational Visibility: Features integrated health check endpoints crucial for monitoring and system observability.

Rapid Deployment Guide

Initiate the 1MCP service swiftly:

0. Installation Options (Select One)

Executable Binaries (Recommended: Zero Dependencies)

Obtain the platform-specific compressed archive from the most recent release:

• Linux (x64): 1mcp-linux-x64
• Linux (ARM64): 1mcp-linux-arm64
• Windows (x64): 1mcp-win32-x64.exe
• macOS (ARM64): 1mcp-darwin-arm64
• macOS (Intel): 1mcp-darwin-x64

bash

Linux Example:

curl -L -o 1mcp-linux-x64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64.tar.gz tar -xzf 1mcp-linux-x64.tar.gz sudo mv 1mcp /usr/local/bin/ && sudo chmod +x /usr/local/bin/1mcp rm 1mcp-linux-x64.tar.gz 1mcp --version

Refer to the Installation Guide for platform-specific detailed instructions.

NPM/Node.js Environment

Leverage standard Node package managers:

bash

Execute directly without installing globally

npx -y @1mcp/agent --help

Or install globally for convenience

npm install -g @1mcp/agent

1. Register Target MCP Services

Integrate the required backend services using their respective execution methods:

bash

Binary execution method:

1mcp mcp add context7 -- npx -y @upstash/context7-mcp 1mcp mcp add sequential -- npx -y @modelcontextprotocol/server-sequential-thinking

NPM execution method:

npx -y @1mcp/agent mcp add context7 -- npx -y @upstash/context7-mcp

2. Initiate the 1MCP Aggregator

bash

Using binary:

1mcp

Using NPM:

npx -y @1mcp/agent

The gateway defaults to operating on http://127.0.0.1:3050, reporting the status of all integrated MCP services.

3. Client Integration (AI Tool Configuration)

Configure your IDE/Assistant client to point to the unified endpoint:

For Cursor: Update ~/.cursor/mcp.json with:

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

For VSCode: Update settings.json:

{ "servers": { "1mcp": { "url": "http://127.0.0.1:3050/mcp?app=vscode" } } }

4. Operational Verification

Confirm service connectivity:

bash 1mcp mcp status

Access the system diagnostics portal at: http://127.0.0.1:3050/health

Command Line Interface Reference

1MCP exposes a set of administrative commands for configuration management:

Core Execution

• 1mcp [serve] or npx -y @1mcp/agent [serve] - Launches the core aggregation engine (default action).
• Options: --transport (stdio, http, sse), --config, --port.

Service Registry Management

• 1mcp mcp add <alias> - Registers a new backend service.
• 1mcp mcp remove <alias> - Deletes a registered service.
• 1mcp mcp list - Displays the inventory of managed MCP services.
• 1mcp mcp status [alias] - Reports the operational state of specific or all services.
• 1mcp mcp enable/disable <alias> - Toggles service activity.

For comprehensive command syntax, consult the Commands Reference.

Runtime Requirements

• Binary Mode: Execution environment is entirely self-contained; no external runtime prerequisites.
• NPM Mode: Requires [Node.js] (v21+) and a package manager (npm/pnpm).

Operational Usage

Execution methods:

bash

Binary execution:

1mcp --transport stdio

NPM execution:

npx -y @1mcp/agent --port 8080

Detailed parameter documentation is available via: Configuration Deep Dive.

Containerization with Docker

Docker deployment is supported via two image flavors available on GHCR:

• latest: Comprehensive image including supplementary tooling (uv, bun).
• lite: Minimalistic image containing only essential package managers (npm, pnpm, yarn).

Standard HTTP Startup (Ensure host binding to 0.0.0.0):

bash

Pull and run the full image, mapping port 3050

docker pull ghcr.io/1mcp-app/agent:latest docker run -d -p 3050:3050 -e ONE_MCP_HOST=0.0.0.0 ghcr.io/1mcp-app/agent

Server Tagging Strategy

Tags enable fine-grained control over which backend services are exposed based on client needs or service capability. Services are labeled in the configuration file (e.g., filesystem, network).

When operating in stdio mode, filter the active set using advanced boolean expressions via the --tag-filter argument:

bash

Execute only servers tagged 'web' OR 'api'

1mcp --transport stdio --tag-filter "web,api"

Execute servers tagged 'api' AND NOT tagged 'test'

1mcp --transport stdio --tag-filter "api and not test"

For HTTP/SSE clients, filtering is applied directly in the connection URL query parameters.

Configuration Mechanics

Configuration precedence follows the hierarchy: Command-Line Arguments > Environment Variables > Persistent JSON Configuration.

Consult the Configuration Deep Dive for environment variable mappings (e.g., ONE_MCP_PORT).

Security Measures (AuthN)

To mandate secure access, enable OAuth 2.1 provider functionality using the --enable-auth launch flag. This configures 1MCP to manage authorization tokens for client access.

System Status & Observability

Monitoring health is facilitated through standardized endpoints:

• GET /health: Comprehensive diagnostic report (Configuration, Component Status).
• GET /health/ready: Checks if the gateway is fully initialized and routing requests (Readiness Probe).

Status indicators include healthy, degraded, and unhealthy (mapped to appropriate HTTP response codes).

Internal Mechanics

1MCP functions as a robust intermediary. It initiates target MCP services as child processes, intercepts their I/O streams (or proxies HTTP), and intelligently routes incoming requests from AI assistants to the correct, context-aware backend based on configuration and filtering rules.

Contribution Guidelines

We encourage external contributions. Review the CONTRIBUTING.md document for guidelines on coding standards and submission protocols.

Licensing Information

Distributed under the terms of the Apache License, Version 2.0. See the LICENSE file for full legal text.

=== Business Tools Context === Business Management Tools encompass all systematic approaches—applications, controls, and methodologies—used by enterprises to maintain market relevance, adapt to dynamic commercial landscapes, and enhance overall operational efficacy. The selection and tailored application of these tools are paramount to achieving sustainable value, exceeding mere adoption of the newest available technology.