MCP Agent Proxy

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

Built for/with Mastra ❤️

Support for other Agent servers coming soon! Contribute? 😉

Quick Start

Add this to your MCP client's configuration:

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

That's it! The proxy automatically connects to http://localhost:4111 and exposes all agents as MCP tools.

https://github.com/user-attachments/assets/e816c0cb-48e5-471b-8ff4-9107bd6e8bb6

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 Mastra servers at runtime | | disconnectServer | Remove dynamically connected servers |

The Network Effect

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

Your MCP Client → MCP Proxy → Mastra Server → Agents -> MCP Proxy -> Other Agent Servers → 🚀 Agents

One configuration line unlocks entire ecosystems of AI capabilities.

Common Configurations

Multiple Servers

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["@mashh/mcp-agent-proxy"],
      "env": {
        "MASTRA_SERVERS": "http://localhost:4111 http://localhost:4222"
      }
    }
  }
}

Cloud + Local

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["@mashh/mcp-agent-proxy"],
      "env": {
        "MASTRA_SERVERS": "https://prod.vercel.app http://localhost:4111"
      }
    }
  }
}

From Source (Development)

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "node",
      "args": ["/path/to/mcp-agent-proxy/dist/mcp-server.js"],
      "env": {
        "MASTRA_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 | | ----------------- | ----------------------- | --------------------------------- | | MASTRA_SERVERS | http://localhost:4111 | Space/comma-separated server URLs | | 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:

• minimal-config.json - Zero setup
• multi-server-config.json - Multiple local servers
• cloud-config.json - Cloud deployment
• network-effect-config.json - Recursive networks
• mastra-server-with-mcp.js - Network-aware server

For advanced configuration options, see CONFIGURATION.md.

Troubleshooting

NPX Issues:

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

Port Conflicts:

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

Connection Issues:

• Ensure Mastra servers are running and accessible
• Check firewall settings and server URLs

Debug Mode:

DEBUG=mastra:* npx @mashh/mcp-agent-proxy

Development

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

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.