Content
# 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](https://github.com/mastra-ai/mastra) ❤️ and [LangGraph](https://github.com/langchain-ai/langgraph) 🦜🕸️ servers! 🎉
## Quick Start
Add this to your MCP client's configuration:
```json
{
"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)
```json
{
"mcpServers": {
"mcpAgentProxy": {
"command": "npx",
"args": ["mcp-agent-proxy"],
"env": {
"AGENT_SERVERS": "http://localhost:4111 http://localhost:2024"
}
}
}
}
```
### Cloud + Local (Mixed Mastra and LangGraph)
```json
{
"mcpServers": {
"mcpAgentProxy": {
"command": "npx",
"args": ["mcp-agent-proxy"],
"env": {
"AGENT_SERVERS": "https://my-mastra.vercel.app http://localhost:2024"
}
}
}
}
```
### From Source (Development)
```json
{
"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:**
```bash
npx clear-npx-cache
npx mcp-agent-proxy@latest
```
**Port Conflicts:**
```json
"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:**
```bash
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
```bash
# 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
```bash
# Build and test
pnpm build
pnpm test
pnpm test:integration
# Code quality
pnpm lint
pnpm format
pnpm format:check
```
#### MCP Protocol Testing
```bash
# 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:
```bash
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.
---
<div align="center">
**[📖 Configuration Guide](CONFIGURATION.md) • [🚀 Examples](examples/) • [🐛 Issues](https://github.com/mastra-ai/mcp-agent-proxy/issues) • [💬 Discussions](https://github.com/mastra-ai/mcp-agent-proxy/discussions)**
_Building the Internet of Agents, one connection at a time._
</div>
