Mcp Agent Proxy

MCP Agent Proxy

[](https://badge.fury.io/js/mcp-agent-proxy) [](https://opensource.org/licenses/MIT) [](https://github.com/mashh-lab/mcp-agent-proxy/actions)

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/](examples/) directory:

• [mcp.json](examples/minimal-config.json) - Zero setup
• [multi-server-config.json](examples/multi-server-config.json) - Multiple local servers
• [vercel-config.json](examples/vercel-config.json) - Cloud deployment

For advanced configuration options, see [CONFIGURATION.md](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](CONTRIBUTING.md) for details.

License

MIT License - see [LICENSE](LICENSE) file for details.

---

[📖 Configuration Guide](CONFIGURATION.md) • [🚀 Examples](examples/) • 🐛 Issues • 💬 Discussions

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mashh-lab
• Source: mashh-lab/mcp-agent-proxy
• License: MIT

Install and usage instructions live in the source repository linked above.