An MCP (Model Context Protocol) proxy server that allows selective re-exposure of tools, resources, and prompts from backend MCP servers through configurable "groups". Keep your AI agents focused by exposing only the tools they need, with smart resource management and prompt prioritization.
Modern MCP servers often expose 20-50+ tools with verbose descriptions and numerous optional parameters, creating serious context window bloat that harms AI agent performance and increases costs.
Backend MCP servers often expose all their tools at once. You might only need 5 specific tools from a server, but it exposes all 50. Every tool definition—including description and full parameter schema—gets loaded into the agent's context window. This wastes precious context tokens on irrelevant tools.
In Claude Code, denying tool permissions doesn't solve the problem. Even when you mark a tool as "deny", its complete definition—including description and full parameter schema—still gets loaded into the agent's context window on every conversation turn. This wastes precious context tokens on tools the agent can't even use.
Tool authors frequently write overly verbose descriptions. A simple "get current time" tool might have a 200-word description explaining timezones, edge cases, and implementation details. Multiply this by 50 tools and you've consumed thousands of tokens before the agent even reads your first message.
Optional parameters bloat the context. Many tools expose 10-15 parameters where only 2-3 are commonly used. Each parameter definition—with its type, description, constraints, and examples—consumes tokens. Most agents will never use dewpoint_precision or barometric_pressure_unit, but these parameters still occupy valuable context space.
You can't easily fix this at the MCP client level. You're connecting to the full backend server and receiving its entire tool catalog. You can't selectively expose tools, override verbose descriptions, or hide unnecessary parameters without a proxy layer.
MCP Proxy Processor completely excludes unwanted tools from your agent's context. The agent never sees them, never wastes tokens on them, and never gets confused by irrelevant options.
- Curate tool sets: Reduce 50 backend tools to 5 focused tools. Save thousands of context tokens per conversation.
- Rewrite verbose descriptions: Transform 200-word descriptions into clear, concise 20-word summaries.
- Hide unnecessary parameters: Remove rarely-used optional parameters from the agent-visible schema entirely. The agent sees only the 3 parameters that matter.
- Inject hidden parameters: Add API keys, default values, and configuration as constants—agents never see or waste tokens on them.
- Selective resource exposure: Choose which files, APIs, or data sources to expose from backend servers
- URI template matching: Use RFC 6570 templates to match multiple resource URIs with patterns
- Priority-based fallback: Configure multiple servers for the same resource with automatic failover
- Conflict detection: Identify overlapping resource patterns and resolve conflicts
- Prompt curation: Select specific prompts from backend servers to expose to agents
- Argument pass-through: Preserve prompt arguments and requirements from backend definitions
- Priority ordering: Set fallback chains for prompts across multiple backend servers
- Deduplication: Automatically handle duplicate prompt names with smart priority resolution
- Organize by purpose: Create different groups for different tasks (coding, research, financial analysis), each optimized for its specific workflow.
- Improve agent performance: Cleaner, smaller tool sets help agents make better decisions faster with less confusion.
You have two backend MCP servers:
- time server:
current_time(get time in any timezone),convert_timezone - calculator server:
calculate,solve_equation,differentiate,integrate,mean,variance,standard_deviation,median,mode
You want to expose only current_time, calculate, and solve_equation to your agent, AND the solve_equation description is confusing. With MCP Proxy Processor:
- Define a "standard_tools" group containing these three tools
- Override the
solve_equationdescription with a clearer version - Configure your agent to use the "standard_tools" MCP server
- Agent sees exactly 3 clean, well-described tools
You can create multiple groups for different purposes:
- standard_tools: Time and basic math for general use
- financial_tools: Statistics, calculator, and web search for financial analysis
- coding_tools: File operations, documentation search, and linting
Run directly with npx (no installation needed):
npx -y @hughescr/mcp-proxy-processor@latest --helpOr install globally:
npm install -g @hughescr/mcp-proxy-processor
mcp-proxy --helpNote: Built with Bun, runs on Node.js 24+ and any Node-compatible runtime (npm, yarn, bun, pnpm).
- Node.js 24.x or later
- Backend MCP servers you want to proxy (e.g.,
@modelcontextprotocol/server-time,@modelcontextprotocol/server-calculator)
Find where MCP Proxy Processor stores configuration files:
npx @hughescr/mcp-proxy-processor@latest config-path
# or if installed globally:
mcp-proxy config-pathThis will print the config directory path for your platform:
- macOS:
~/Library/Preferences/@hughescr-mcp-proxy-processor/ - Linux:
~/.config/@hughescr-mcp-proxy-processor/ - Windows:
%APPDATA%\@hughescr-mcp-proxy-processor\Config\
Create a backend-servers.json file in your config directory to define your backend MCP servers (uses Claude Desktop's mcp.json format):
{
"mcpServers": {
"time": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-time"]
},
"calculator": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-calculator"]
}
}
}Launch the interactive admin interface to discover and configure tools:
npx @hughescr/mcp-proxy-processor@latest admin
# or if installed globally:
mcp-proxy adminThe admin interface lets you:
- Discover Tools: Connect to backend servers and see all available tools
- Create Groups: Create new groups for different purposes
- Add Tools: Add tools to groups by selecting from available backend tools
- Override Definitions: Improve tool names and descriptions
- Save: Automatically writes configuration to your config directory
Admin Interface Workflow:
- Use arrow keys to navigate menus
- Press Enter to select options
- Type to enter text in prompts
- Press Ctrl+C to exit at any time
Create a groups.json file in your config directory (use mcp-proxy config-path to find the location).
Define your tool groups:
{
"groups": {
"standard_tools": {
"name": "standard_tools",
"description": "Basic tools for everyday use",
"tools": [
{
"serverName": "time",
"originalName": "get_current_time"
},
{
"serverName": "calculator",
"originalName": "calculate"
},
{
"serverName": "calculator",
"originalName": "solve",
"description": "Solve algebraic equations for a variable. Provide the equation as a string with one variable (e.g., '2*x + 5 = 13' or 'y^2 - 4 = 0'). This override fixes the confusing original description."
}
],
"resources": [],
"prompts": []
}
}
}Add the proxy to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"standard_tools": {
"command": "npx",
"args": ["-y", "@hughescr/mcp-proxy-processor@latest", "serve", "standard_tools"]
},
"financial_tools": {
"command": "npx",
"args": ["-y", "@hughescr/mcp-proxy-processor@latest", "serve", "financial_tools"]
}
}
}If installed globally:
{
"mcpServers": {
"standard_tools": {
"command": "mcp-proxy",
"args": ["serve", "standard_tools"]
}
}
}Restart Claude Desktop. Your agent now has access to the curated tool sets!
Configuration files are stored in a platform-specific directory. Use mcp-proxy config-path to find the location.
The backend-servers.json file uses the same format as Claude Desktop's mcp.json:
{
"mcpServers": {
"server-name": {
"command": "command-to-run",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR": "value"
}
}
}
}The config/groups.json file defines tool groups:
{
"groups": {
"group-name": {
"name": "group-name",
"description": "Optional group description",
"tools": [
{
"serverName": "backend-server-name",
"originalName": "original_tool_name",
"name": "optional-override-name",
"description": "Optional override description",
"inputSchema": {},
"argumentMapping": {}
}
],
"resources": [
{
"serverName": "backend-server-name",
"uri": "resource://uri"
}
],
"prompts": [
{
"serverName": "backend-server-name",
"name": "prompt-name"
}
]
}
}
}Tool Fields:
serverName(required): Backend server providing the tooloriginalName(required): Tool name from backend servername(optional): Override the tool namedescription(optional): Override the tool descriptioninputSchema(optional): Override the input schemaargumentMapping(optional): Transform arguments before sending to backend
Resource Fields:
serverName(required): Backend server providing the resourceuri(required): Exact URI or RFC 6570 URI template (e.g.,file:///{path})
Prompt Fields:
serverName(required): Backend server providing the promptname(required): Prompt name from backend server
Argument mapping allows you to transform tool call arguments from the AI agent format to the backend server format. This is useful for:
- Adding default values for optional parameters
- Injecting authentication credentials or API keys
- Renaming parameters between client and backend
- Restructuring complex argument schemas
- Hiding unnecessary parameters from the agent (saves context tokens)
Make a required backend parameter optional for agents by providing a default:
{
"serverName": "time",
"originalName": "get_current_time",
"description": "Get current time (defaults to America/Los_Angeles)",
"inputSchema": {
"properties": {
"timezone": {
"type": "string",
"description": "IANA timezone (optional)"
}
}
},
"argumentMapping": {
"type": "template",
"mappings": {
"timezone": {
"type": "default",
"source": "timezone",
"default": "America/Los_Angeles"
}
}
}
}How it works:
- The agent sees
timezoneas optional - If agent omits it, the mapping adds
"America/Los_Angeles" - Backend always receives a timezone parameter
Template Mappings (declarative, recommended):
- passthrough: Pass parameter through unchanged
- constant: Always use a fixed value (hidden from agent)
- default: Use client value if provided, otherwise use default
- omit: Remove parameter from agent-visible schema
- rename: Show different parameter name to agent
JSONata Expressions (for complex transformations):
- Conditional logic based on parameter values
- Restructuring nested objects
- Array transformations
- String manipulation
Each hidden/omitted parameter saves 15-30 context tokens. For example:
- Backend tool with 15 parameters, 200-word description
- Agent only needs 3 parameters, 20-word description
- Savings: ~534 tokens per tool
- Across 10 tools: ~5,340 tokens saved
For complete documentation, see Argument Mapping Guide.
Start the MCP proxy server for a specific group:
mcp-proxy serve standard_toolsThis starts an MCP server (stdio transport) exposing only the tools defined in the "standard_tools" group.
Launch the interactive admin interface:
mcp-proxy adminUse this to:
- View available backend tools
- Create and edit groups
- Add/remove tools from groups
- Override tool definitions
- Configure argument mappings
- Save configurations
List all configured groups:
mcp-proxy list-groupsShow detailed information about a specific group:
mcp-proxy describe-group standard_toolsList all configured backend servers:
mcp-proxy list-backendsValidate configuration files without starting servers:
mcp-proxy validateDisplay the configuration directory location:
mcp-proxy config-path
# With verbose output showing all config file paths:
mcp-proxy config-path --verboseThis is useful for:
- Finding where to create/edit config files manually
- Scripting:
cd $(mcp-proxy config-path) - Troubleshooting configuration issues
Create a focused group for financial analysis that includes Excel, calculator, web search, and browser tools:
{
"groups": {
"financial_tools": {
"name": "financial_tools",
"description": "Tools for financial analysis",
"tools": [
{
"serverName": "calculator",
"originalName": "calculate"
},
{
"serverName": "calculator",
"originalName": "statistics"
},
{
"serverName": "excel",
"originalName": "read_workbook"
},
{
"serverName": "search",
"originalName": "brave_web_search",
"description": "Search for financial information, SEC filings, market data, and company information."
},
{
"serverName": "browser",
"originalName": "browser_navigate"
},
{
"serverName": "browser",
"originalName": "browser_snapshot"
}
]
}
}
}Now when Claude analyzes financial data, it only sees 6 focused tools instead of 30+ tools from all four backend servers.
Create a research-focused group with web search and browser automation:
{
"groups": {
"research_tools": {
"name": "research_tools",
"description": "Tools for web research and browser automation",
"tools": [
{
"serverName": "search",
"originalName": "brave_web_search"
},
{
"serverName": "search",
"originalName": "perplexity_search",
"description": "AI-powered search with reasoning. Use for complex research questions requiring synthesis."
},
{
"serverName": "browser",
"originalName": "browser_navigate"
},
{
"serverName": "browser",
"originalName": "browser_snapshot"
},
{
"serverName": "time",
"originalName": "get_current_time",
"description": "Get current time for timestamping research findings."
}
]
}
}
}Configure multiple groups in Claude Desktop for different workflows:
{
"mcpServers": {
"quick_tools": {
"command": "npx",
"args": ["-y", "@hughescr/mcp-proxy-processor@latest", "serve", "standard_tools"]
},
"financial_analysis": {
"command": "npx",
"args": ["-y", "@hughescr/mcp-proxy-processor@latest", "serve", "financial_tools"]
},
"research": {
"command": "npx",
"args": ["-y", "@hughescr/mcp-proxy-processor@latest", "serve", "research_tools"]
}
}
}Claude Desktop will show all groups. You can enable/disable groups based on your current task, keeping context windows clean.
┌─────────────────┐
│ AI Agent │
│ (Claude, etc.) │
└────────┬────────┘
│ stdio
▼
┌─────────────────────────┐
│ Frontend MCP Server │
│ (Group: standard_tools)│
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Middleware Layer │
│ (Group mapping & │
│ tool overrides) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Backend MCP Clients │
│ (time, calculator) │
└─────────────────────────┘
- Argument Mapping Guide - Transform tool parameters and optimize context usage
- Resources & Prompts Guide - Configure resources and prompts with priority fallback
- Project Configuration Example - Real-world configuration used to develop this project
- Troubleshooting - Common issues, debugging tips, and FAQ
- Development Guide - Build from source, run tests, contribute to the project
For common issues, debugging tips, and frequently asked questions, see TROUBLESHOOTING.md.
Quick tips:
- Backend server won't start: Verify the command path and required dependencies
- Tool not found errors: Use
mcp-proxy adminto discover correct tool names - Claude Desktop issues: Check config file syntax and restart Claude Desktop
- Protocol errors: Ensure backend servers use stdio transport correctly
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch from
develop - Make your changes with tests
- Run
bun run full-testto validate - Submit a pull request to
develop
See DEVELOPMENT.md for detailed setup instructions, testing procedures, and development guidelines.
Craig R. Hughes craig.git@rungie.com