MCP Gateway (mcpg)
Routes requests to an upstream GitHub MCP server, allowing agents to discover and invoke GitHub-related tools such as repository file creation and reading through the gateway.
Routes requests to an upstream Slack MCP server, allowing agents to discover and invoke Slack-related tools through the gateway.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcpg
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 --yesThis will:
Detect your AI agent configuration (supports Claude Code and OpenCode)
Show you all configured MCP servers across your config files
Let you select which servers to route through mcpg
Create
.mcpg.jsonwith your upstream server configsUpdate 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:
Create
.mcpg.jsonin your project directory:
{
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"]
}
}
}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 |
| Find tools matching a query across all servers |
| Get detailed schema for a specific tool |
| Execute a tool on an upstream server |
| 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 runSee 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 outputmcpg install
The install command bootstraps mcpg for a project by:
Detecting your AI agent - Finds supported agent configurations in the current project
Discovering MCP servers - Reads servers from all agent config sources, tracking which file each came from
Server selection - Interactive multi-select to choose which servers to route through mcpg (or
--yesto select all)Creating
.mcpg.json- Writes the gateway config with your selected upstream serversUpdating agent config - Adds mcpg to your agent's MCP config and disables the migrated servers
Creating backups - Backs up any modified config files (
.backupextension)
After running install, restart your AI agent for changes to take effect.
mcpg uninstall
The uninstall command reverses the install process:
Removing
.mcpg.json- Deletes the gateway configurationRestoring backups - Restores agent config files from
.backupfiles created during install
Configuration
mcpg looks for its gateway configuration in the following order:
$MCPG_CONFIGenvironment variable./.mcpg.json(project directory)~/.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 requesturl: 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-IdheaderNo 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:
.mcp.json.claude/settings.local.json
User-scoped:
~/.claude.json~/.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:
opencode.json(project directory)~/.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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
An MCP gateway for teams deploying AI tools at scale to employee-facing and headless agents.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAggregates 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.22MIT
- AlicenseAqualityDmaintenanceAggregates tools from multiple MCP servers, acting as a proxy to provide unified access to various AI agents and tools.1020 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.2MIT
- AlicenseAqualityCmaintenancePuts 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.3MIT