mcp-agent-proxy

MCP Agent Proxy

Connect any MCP client to any agent server - creating an "Internet of Agents" through simple, composable primitives.

Supports Mastra ❤️ and LangGraph 🦜🕸️ servers! 🎉

Quick Start

Add this to your MCP client's configuration:

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["mcp-agent-proxy@latest"]
    }
  }
}

That's it! The proxy lets your MCP client connect to different agent servers and exposes agent interactions as MCP tools. It automatically detects agent server types and adapts accordingly.

https://github.com/user-attachments/assets/9eaf1d36-298f-430f-b9e8-37e921cce2d1

What This Does

Instead of building complex protocols, we provide 5 simple tools that let agents discover, connect, and orchestrate across unlimited networks:

Tool	Purpose
listAgents	Discover available agents across all servers
describeAgent	Get detailed agent capabilities for intelligent routing
callAgent	Execute any agent with smart conflict resolution
connectServer	Dynamically add new agent servers at runtime
disconnectServer	Remove dynamically connected servers

Supported Server Types

• Mastra: Support for local and remote Mastra servers
• LangGraph: Support for local and remote LangGraph instances
• Extensible: Plugin architecture makes it easy to add support for other agent frameworks

The Network Effect

Agent servers can be MCP clients themselves, creating recursive agent networks:

Your MCP Client → MCP Proxy → Agent Server (Mastra/LangGraph) → Agents -> MCP Proxy -> Other Agent Servers → 🚀 Agents

One configuration line unlocks entire ecosystems of AI capabilities.

MCP Compliance & Features

✅ Fully MCP 2025-03-26 Compliant

• Complete implementation of the latest Model Context Protocol specification

🚀 Multi-Transport Support

• Stdio Transport: Standard MCP client integration (npx mcp-agent-proxy)
• Streamable HTTP: Modern HTTP-based transport with session management
• Legacy SSE: Backward compatibility with existing SSE implementations
• Automatic Detection: Seamlessly switches between transports based on client capabilities

Common Configurations

Multiple Servers (Mixed Types)

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["mcp-agent-proxy"],
      "env": {
        "AGENT_SERVERS": "http://localhost:4111 http://localhost:2024"
      }
    }
  }
}

Cloud + Local (Mixed Mastra and LangGraph)

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["mcp-agent-proxy"],
      "env": {
        "AGENT_SERVERS": "https://my-mastra.vercel.app http://localhost:2024"
      }
    }
  }
}

From Source (Development)

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "node",
      "args": ["/path/to/mcp-agent-proxy/dist/mcp-server.js"],
      "env": {
        "AGENT_SERVERS": "http://localhost:4111"
      }
    }
  }
}

Usage Examples

Basic Agent Call:

Can you call the weatherAgent to get the current weather in New York City?

Network Exploration

Explore the agents you're connected to

Smart Conflict Resolution:

I need to use the weatherAgent from server1 specifically, not the default one

Dynamic Network Expansion:

Connect to the ML specialists at https://ml-specialists.vercel.app and then use their modelTrainer agent

Environment Variables

Variable	Default	Description
AGENT_SERVERS	(none)	Space/comma-separated server URLs (supports Mastra and LangGraph)
MCP_SERVER_PORT	3001	Proxy server port
MCP_TRANSPORT	http	Transport method (stdio/http)

Examples & Advanced Usage

Ready-to-use configurations in the examples/ directory:

• mcp.json - Zero setup
• multi-server-config.json - Multiple local servers
• vercel-config.json - Cloud deployment

For advanced configuration options, see CONFIGURATION.md.

Troubleshooting

NPX Issues:

npx clear-npx-cache
npx mcp-agent-proxy@latest

Port Conflicts:

"env": { "MCP_SERVER_PORT": "3002" }

Connection Issues:

• Ensure agent servers are running and accessible
• Check firewall settings and server URLs
• For LangGraph: Default port is usually 2024 (langgraph dev)
• For Mastra: Default port is usually 4111

Debug Mode:

DEBUG=mastra:* npx mcp-agent-proxy

Development & Testing

Validation Workflows

We've implemented comprehensive validation workflows to ensure code quality and MCP protocol compliance:

Quick Commands

# Quick validation (build + test + lint + format)
pnpm validate:quick

# Full validation (includes integration tests + health checks)
pnpm validate:full

# CI validation (includes coverage + dead code analysis)
pnpm validate:ci

Individual Commands

# Build and test
pnpm build
pnpm test
pnpm test:integration

# Code quality
pnpm lint
pnpm format
pnpm format:check

MCP Protocol Testing

# Test MCP protocol compliance
pnpm mcp:test

# Test security features
pnpm security:test

# Manual server testing
pnpm start           # Start server
pnpm check          # Check running server (requires jq)

Test Coverage

• 355 total tests covering all components
• Unit tests for all tools, plugins, and configuration
• Integration tests for MCP protocol compliance
• Security tests for origin validation and session management
• Health checks for server monitoring

Available Scripts

Use pnpm run to see all available scripts, or use these common ones:

pnpm dev             # Build and start development server
pnpm test            # Run all tests
pnpm test:watch      # Run tests in watch mode
pnpm build           # Build for production
pnpm lint            # Run ESLint
pnpm format          # Format code with Prettier

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

📖 Configuration Guide • 🚀 Examples • 🐛 Issues • 💬 Discussions

Building the Internet of Agents, one connection at a time.