One MCP

Open Source

MCP proxy server for progressive tool discovery and reduced token usage. Connect multiple MCP servers through a single proxy that loads tools on-demand.

Overview

One MCP is an open-source Model Context Protocol server from the AI Code Toolkit that solves a critical problem: traditional MCP setups load ALL tools from ALL servers at startup, consuming 40,000+ tokens before any work begins.

One MCP acts as an intelligent proxy, exposing only 2 meta-tools (~400 tokens) initially. Tools are loaded on-demand when needed, reducing initial token usage by 90%+.

Key Benefits

90%+ Token Reduction

Instead of loading 40,000+ tokens of tool descriptions at startup, agents see only ~400 tokens for 2 meta-tools. Tools load progressively as needed.

Multi-Server Aggregation

Connect to multiple MCP servers (stdio, HTTP, SSE) through a single proxy. Replace 10+ individual server configs with one unified connection.

Tool Blacklisting

Prevent specific tools from being executed with configurable blacklists. Control which tools agents can access on a per-server basis.

Flexible Configuration

Support for YAML and JSON configs with environment variable interpolation. Mix local stdio servers with remote HTTP/SSE endpoints.

Available MCP Tools

describe_tools

Retrieve information about available tools from connected MCP servers. Supports optional server filtering.

• List tools from all servers or filter by server name
• Get tool schemas and descriptions
• Discover available capabilities on-demand

use_tool

Execute tools from connected servers through the proxy with automatic routing.

• Execute any tool from any connected server
• Automatic server routing based on tool name
• Pass arguments as structured objects

How One MCP Works

Initial Connection

Agent connects to One MCP and sees only 2 meta-tools (describe_tools, use_tool) consuming ~400 tokens instead of 40,000+.

Tool Discovery

When the agent needs tools, it calls describe_tools to discover available capabilities from specific servers or all connected servers.

Tool Execution

Agent calls use_tool with the tool name and arguments. One MCP routes the request to the correct backend server.

Progressive Loading

Tools are cached after first discovery. The agent builds up its tool knowledge progressively as needed.

Common Use Cases

Server Consolidation

Replace 10+ individual MCP server configurations with a single One MCP proxy connection.

Infrastructure Simplification

Hybrid Environments

Mix local development tools (stdio) with remote company-wide services (HTTP/SSE) in a single config.

Mixed Transport

Token Optimization

Reduce context window consumption for long-running agent sessions with many available tools.

Cost Reduction

Tool Access Control

Blacklist dangerous tools like write_file or delete_file while keeping read-only access available.

Security

Installation & Configuration

Quick Start

Initialize One MCP configuration in your project:

npx @agiflowai/one-mcp init

MCP Configuration

Add the following to your AI coding tool's MCP settings (e.g., Claude Code, Cursor, Windsurf):

{
  "mcpServers": {
    "one-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agiflowai/one-mcp",
        "mcp-serve",
        "--config",
        "./mcp-config.yaml"
      ]
    }
  }
}

Server Configuration (mcp-config.yaml)

Define your MCP servers with support for stdio and HTTP/SSE transports:

mcpServers:
  # Stdio server (local command)
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/Documents"]
    config:
      instruction: "File system access"
      toolBlacklist:
        - write_file
        - delete_file

  # HTTP/SSE server (remote)
  company-tools:
    url: "https://mcp.company.com/sse"
    transport: sse
    config:
      omitToolDescription: true  # Compact listings

  # Disabled server (skipped)
  experimental:
    command: npx
    args: ["-y", "experimental-mcp"]
    disabled: true

CLI Commands

mcp-serve

Start the MCP proxy server (stdio, HTTP, or SSE transport)

init

Initialize configuration file in current directory

list-tools

Display all tools from configured MCP servers

describe-tools

Get detailed information about specific tools

use-tool

Execute a tool directly from command line

Server Options

Option	Purpose	Default
`-c, --config`	Config file path (YAML/JSON)	Required
`-t, --type`	Transport type (stdio/http/sse)	stdio
`-p, --port`	HTTP/SSE port	3000
`--host`	HTTP/SSE host binding	localhost
`--no-cache`	Bypass configuration caching	false

Configuration Options

Environment Variables

Use $${VAR_NAME} syntax for environment variable interpolation in your YAML configuration files.

Tool Blacklisting

Add toolBlacklist array to prevent specific tools from being discovered or executed. Useful for restricting write operations.

Compact Descriptions

Set omitToolDescription: true to show only tool names without verbose descriptions for faster discovery.

Server Instructions

Add custom instruction text to provide context about each server's purpose to the AI agent.

Works With

One MCP is part of the AI Code Toolkit and works seamlessly with other open-source MCPs:

Scaffold MCP

Generate standardized code from templates

Architect MCP

Enforce patterns and validate code

Powertool

MCP proxy with Agiflow integration

Next Steps

Explore Scaffold MCP

Learn how Scaffold MCP generates standardized code from templates for consistent project bootstrapping.

Learn about Scaffold MCP

View on GitHub

Explore the One MCP source code, contribute, or report issues on GitHub.

Visit GitHub Repository

Get Started with Agiflow

Overview

One MCP acts as an intelligent proxy, exposing only 2 meta-tools (~400 tokens) initially. Tools are loaded on-demand when needed, reducing initial token usage by 90%+.

Key Benefits

90%+ Token Reduction

Instead of loading 40,000+ tokens of tool descriptions at startup, agents see only ~400 tokens for 2 meta-tools. Tools load progressively as needed.

Multi-Server Aggregation

Connect to multiple MCP servers (stdio, HTTP, SSE) through a single proxy. Replace 10+ individual server configs with one unified connection.

Tool Blacklisting

Prevent specific tools from being executed with configurable blacklists. Control which tools agents can access on a per-server basis.

Flexible Configuration

Support for YAML and JSON configs with environment variable interpolation. Mix local stdio servers with remote HTTP/SSE endpoints.

Available MCP Tools

describe_tools

Retrieve information about available tools from connected MCP servers. Supports optional server filtering.

• List tools from all servers or filter by server name
• Get tool schemas and descriptions
• Discover available capabilities on-demand

use_tool

Execute tools from connected servers through the proxy with automatic routing.

• Execute any tool from any connected server
• Automatic server routing based on tool name
• Pass arguments as structured objects

How One MCP Works

Initial Connection

Agent connects to One MCP and sees only 2 meta-tools (describe_tools, use_tool) consuming ~400 tokens instead of 40,000+.

Tool Discovery

When the agent needs tools, it calls describe_tools to discover available capabilities from specific servers or all connected servers.

Tool Execution

Agent calls use_tool with the tool name and arguments. One MCP routes the request to the correct backend server.

Progressive Loading

Tools are cached after first discovery. The agent builds up its tool knowledge progressively as needed.

Common Use Cases

Server Consolidation

Replace 10+ individual MCP server configurations with a single One MCP proxy connection.

Infrastructure Simplification

Hybrid Environments

Mix local development tools (stdio) with remote company-wide services (HTTP/SSE) in a single config.

Mixed Transport

Token Optimization

Reduce context window consumption for long-running agent sessions with many available tools.

Cost Reduction

Tool Access Control

Blacklist dangerous tools like write_file or delete_file while keeping read-only access available.

Security

Installation & Configuration

Quick Start

Initialize One MCP configuration in your project:

npx @agiflowai/one-mcp init

MCP Configuration

Add the following to your AI coding tool's MCP settings (e.g., Claude Code, Cursor, Windsurf):

{
  "mcpServers": {
    "one-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@agiflowai/one-mcp",
        "mcp-serve",
        "--config",
        "./mcp-config.yaml"
      ]
    }
  }
}

Server Configuration (mcp-config.yaml)

Define your MCP servers with support for stdio and HTTP/SSE transports:

mcpServers:
  # Stdio server (local command)
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/Documents"]
    config:
      instruction: "File system access"
      toolBlacklist:
        - write_file
        - delete_file

  # HTTP/SSE server (remote)
  company-tools:
    url: "https://mcp.company.com/sse"
    transport: sse
    config:
      omitToolDescription: true  # Compact listings

  # Disabled server (skipped)
  experimental:
    command: npx
    args: ["-y", "experimental-mcp"]
    disabled: true

Option

Purpose

Default

-c, --config

Config file path (YAML/JSON)

Required

-t, --type

Transport type (stdio/http/sse)

stdio

-p, --port

HTTP/SSE port

3000

--host

HTTP/SSE host binding

localhost

--no-cache

Bypass configuration caching

false

Configuration Options

Environment Variables

Use $${VAR_NAME} syntax for environment variable interpolation in your YAML configuration files.

Tool Blacklisting

Add toolBlacklist array to prevent specific tools from being discovered or executed. Useful for restricting write operations.

Compact Descriptions

Set omitToolDescription: true to show only tool names without verbose descriptions for faster discovery.

Server Instructions

Add custom instruction text to provide context about each server's purpose to the AI agent.