mcp-agent-proxy

The MCP Agent Proxy acts as a bridge between your MCP client and multiple agent servers (such as Mastra and LangGraph). It exposes a lightweight set of tools that let you discover, inspect, and orchestrate interactions with agents across heterogeneous backends. By configuring the proxy in your MCP client, you can connect to local or remote agent servers, and the proxy will automatically detect server types and adapt its behavior to each backend. The resulting tools allow you to explore the network of agents, resolve conflicts, and dynamically expand the connected infrastructure.

Available tools include:

• listAgents: Discover available agents across all connected servers.
• describeAgent: Retrieve detailed capabilities and interfaces for intelligent routing and selection.
• callAgent: Execute a chosen agent with built-in conflict resolution to select the appropriate response.
• connectServer: Dynamically add new agent servers at runtime without restarting the client.
• disconnectServer: Remove servers from the proxy’s dynamic connections.

These tools enable a scalable, multi-backend MCP workflow where agent servers can themselves act as MCP clients to further agents, creating an extensible network of AI capabilities. The proxy supports multiple transports (stdio, HTTP, and legacy SSE) and automatically selects the best transport based on client capabilities.

Prerequisites:\n- Node.js (recommended latest LTS) and npm or a compatible Node package manager.\n- Access to the internet to fetch npm packages.\n\nInstallation steps:\n1) Ensure Node.js and npm are installed. Verify with:\n node -v\n npm -v\n\n2) You can run the MCP Agent Proxy directly via npx without installing globally:\n npx mcp-agent-proxy@latest\n\n3) Alternatively, install the package locally in your project, then run it from your project path:\n npm install mcp-agent-proxy@latest --save-dev\n # Run using node if a script is provided, or use npx as above.\n\n4) Configure your MCP client to point to the proxy using the example configuration below (see mcp_config). You can also set environment variables like MCP_SERVER_PORT and AGENT_SERVERS as needed.\n\n5) Start the proxy and verify it’s reachable by your MCP client. If you encounter port conflicts, adjust MCP_SERVER_PORT via environment variables.

Environment variables you may use:\n- AGENT_SERVERS: Space/comma-separated URLs of agent servers (Mastra, LangGraph, etc.).\n- MCP_SERVER_PORT: Port for the proxy server (default 3001).\n- MCP_TRANSPORT: Transport to use (stdio, http).\n\nCommon issues:\n- Port conflicts: set MCP_SERVER_PORT to an available port.\n- Connectivity: ensure agent servers are running and accessible from the proxy.\n- Transport issues: for local development, stdio or http transports are typically used; verify client compatibility.\n\nDebug tips:\n- Enable verbose logs or debug mode if available (e.g., DEBUG=mastra:* npx mcp-agent-proxy).\n- Use the provided Examples or CONFIGURATION.md as references for advanced setups.