Skip to main content
Glama

mcpg

CI

MCP Gateway - A lightweight MCP server that acts as a gateway to upstream MCP servers with progressive tool discovery.

Note: This project is a work in progress. APIs and configuration formats may change.

What is mcpg?

mcpg is an MCP (Model Context Protocol) server that sits between AI agents (like Claude) and your collection of MCP servers. Instead of loading all tool definitions upfront (consuming thousands of context tokens), it provides progressive discovery through a search-first workflow.

The Problem

Traditional MCP integration loads all tool schemas at startup:

  • 5 MCP servers × ~3,500 tokens each = ~18,000 tokens

  • Severely limits context available for actual work

  • Wasteful when you only need 1-2 tools per task

The Solution

mcpg acts as an MCP gateway server that exposes discovery tools:

  • search - Find relevant tools across all servers (~50 tokens)

  • inspect - Get schema for specific tool (~150 tokens)

  • call - Execute a tool on the upstream server

  • list - List available servers/tools

Result: 99% reduction in context token usage

Related MCP server: Agent Aggregator

Features

  • ✅ MCP server implementation (stdio transport)

  • ✅ Progressive tool discovery via search/inspect/call/list

  • ✅ Upstream MCP client for stdio and HTTP servers

  • ✅ Resources and prompts passthrough

  • ✅ Cursor-based pagination for list operations

  • ✅ Universal configuration layer

  • ✅ Automatic process lifecycle management

  • ✅ Install/uninstall commands for easy setup

  • 🚧 BM25 search ranking (planned)

Quick Start

The fastest way to get started is with mcpg install, which automatically detects your AI agent's MCP servers and configures mcpg as a gateway.

1. Run mcpg install

# Interactive setup - detects your agent and migrates servers
mcpg install

# Or skip prompts and select all servers
mcpg install --yes

This will:

  1. Detect your AI agent configuration (supports Claude Code and OpenCode)

  2. Show you all configured MCP servers across your config files

  3. Let you select which servers to route through mcpg

  4. Create .mcpg.json with your upstream server configs

  5. Update your agent's config to use mcpg instead of the individual servers

2. Restart your AI agent

After install completes, restart your AI agent (e.g., restart Claude Code). The agent will now connect to mcpg and see 4 gateway tools instead of all upstream tools.

Manual Setup

If you prefer to configure manually:

  1. Create .mcpg.json in your project directory:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"]
    }
  }
}
  1. Point your AI agent's MCP config to mcpg:

{
  "mcpServers": {
    "mcpg": {
      "command": "mcpg"
    }
  }
}

Gateway Tools

mcpg exposes 4 gateway tools for progressive discovery:

Tool

Description

search

Find tools matching a query across all servers

inspect

Get detailed schema for a specific tool

call

Execute a tool on an upstream server

list

List configured servers or tools on a server

Resources and Prompts

mcpg passes through resources and prompts from upstream servers:

  • resources/list and resources/read are forwarded to the appropriate upstream server

  • prompts/list and prompts/get are forwarded to the appropriate upstream server

  • Collision detection warns when multiple servers expose the same resource URI or prompt name

Example Workflow

AI Agent                      mcpg                     Upstream Servers
    │                          │                              │
    │ tools/list               │                              │
    │─────────────────────────>│                              │
    │ [search, inspect,        │                              │
    │  call, list]             │                              │
    │<─────────────────────────│                              │
    │                          │                              │
    │ call search(query="file")│                              │
    │─────────────────────────>│  initialize()                │
    │                          │─────────────────────────────>│
    │                          │  tools/list                  │
    │                          │─────────────────────────────>│
    │                          │<─────────────────────────────│
    │ [github] create_file     │                              │
    │ [github] read_file       │                              │
    │<─────────────────────────│                              │
    │                          │                              │
    │ call inspect(github,     │                              │
    │              create_file)│                              │
    │─────────────────────────>│                              │
    │ {name, description,      │                              │
    │  inputSchema}            │                              │
    │<─────────────────────────│                              │
    │                          │                              │
    │ call call(github,        │  tools/call create_file      │
    │           create_file,   │─────────────────────────────>│
    │           {path, content})│                              │
    │                          │<─────────────────────────────│
    │ {result}                 │                              │
    │<─────────────────────────│                              │

JSON-RPC Examples

# Initialize connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}' | cargo run

# List gateway tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | cargo run

# Search for tools
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"echo"}}}' | cargo run

# Call an upstream tool
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"call","arguments":{"server":"everything","tool":"echo","args":{"message":"hello"}}}}' | cargo run

See docs/examples/gateway-demo.sh for a complete working demo.

CLI Commands

# Run the gateway server (default command)
mcpg
mcpg serve

# Install mcpg for a project
mcpg install

# Install options
mcpg install --dry-run    # Preview changes without writing files
mcpg install --yes        # Skip prompts, select all servers
mcpg install -y           # Short form of --yes
mcpg -v install           # Verbose debug output

# Uninstall mcpg from a project
mcpg uninstall

# Uninstall options
mcpg uninstall --dry-run  # Preview changes without writing files
mcpg uninstall --yes      # Skip confirmation prompts
mcpg uninstall -y         # Short form of --yes
mcpg -v uninstall         # Verbose debug output

mcpg install

The install command bootstraps mcpg for a project by:

  1. Detecting your AI agent - Finds supported agent configurations in the current project

  2. Discovering MCP servers - Reads servers from all agent config sources, tracking which file each came from

  3. Server selection - Interactive multi-select to choose which servers to route through mcpg (or --yes to select all)

  4. Creating .mcpg.json - Writes the gateway config with your selected upstream servers

  5. Updating agent config - Adds mcpg to your agent's MCP config and disables the migrated servers

  6. Creating backups - Backs up any modified config files (.backup extension)

After running install, restart your AI agent for changes to take effect.

mcpg uninstall

The uninstall command reverses the install process:

  1. Removing .mcpg.json - Deletes the gateway configuration

  2. Restoring backups - Restores agent config files from .backup files created during install

Configuration

mcpg looks for its gateway configuration in the following order:

  1. $MCPG_CONFIG environment variable

  2. ./.mcpg.json (project directory)

  3. ~/.config/mcpg/config.json (XDG user config)

Config Format

{
  "servers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Transport Types

mcpg supports two transport types for connecting to upstream MCP servers:

Stdio Transport

Runs MCP servers as local subprocesses communicating over stdin/stdout.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"],
      "env": {
        "API_KEY": "optional-env-var"
      },
      "timeout_secs": 30
    }
  }
}

HTTP Transport

Connects to remote MCP servers over HTTP using the Streamable HTTP protocol (MCP 2025-06-18).

{
  "servers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "timeout_secs": 60
    }
  }
}

Configuration Options:

  • timeout_secs (optional): Request timeout in seconds (default: 30)

  • headers (optional): Custom HTTP headers to send with each request

  • url: The MCP endpoint URL (must support Streamable HTTP)

Protocol Details:

  • Uses MCP Streamable HTTP specification (2025-06-18)

  • Single endpoint for all operations (POST to URL)

  • Session management via Mcp-Session-Id header

  • No server-initiated messages in v1 (GET SSE stream not implemented)

Supported Agents

mcpg install detects and migrates servers from Claude Code's config files, checked in priority order:

Project-scoped:

  1. .mcp.json

  2. .claude/settings.local.json

User-scoped:

  1. ~/.claude.json

  2. ~/.claude/mcp_servers.json

When migrating, mcpg adds itself to the highest-priority config source that contains servers, and disables the migrated servers via disabledMcpServers in each source file.

mcpg install detects and migrates servers from OpenCode's config files, checked in priority order:

  1. opencode.json (project directory)

  2. ~/.config/opencode/opencode.json (global)

Both config files use the same flat structure with MCP servers under the mcp key. OpenCode supports "local" (stdio) and "remote" (HTTP) server types.

When migrating, mcpg adds itself to the highest-priority config source that contains servers, and disables the migrated servers by setting enabled: false on each server entry.

Development

For information on building, testing, and contributing to mcpg, see DEVELOPMENT.md.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Aggregates multiple Model Context Protocol servers into a single gateway to provide unified search, description, and execution of tools. It reduces context limit issues by dynamically fetching specific tool schemas only when needed rather than loading all available tools at once.
      22
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI tools to uniformly discover, inspect, and call tools, prompts, and resources from multiple upstream MCP servers through a small set of fixed MCP tools, over stdio or HTTP.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Puts a single MCP endpoint in front of many downstream MCP servers, routing each prompt to the right server and tools so an agent sees a few relevant tools instead of every schema. Reads run automatically, writes require explicit user confirmation via elicitation, and consequential calls are blocked by a risk gate that logs every routing decision and call.
      3
      MIT