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.

---

<div align="center">

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

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

</div>