What is Mcp Agent Proxy

mcp-agent-proxy is an MCP server that exposes agents from local or remote agent servers as MCP tools, enabling seamless connectivity and interaction between different agents.

Use cases

Use cases for mcp-agent-proxy include creating an interconnected network of agents across multiple servers, enabling intelligent routing and execution of tasks, and dynamically managing agent servers in real-time.

How to use

To use mcp-agent-proxy, add the specified configuration to your MCP client’s settings. This includes setting the command to ‘npx’ and specifying the arguments to run the latest version of mcp-agent-proxy. Once configured, it connects automatically to ‘http://localhost:4111’ and exposes all agents as MCP tools.

Key features

Key features of mcp-agent-proxy include agent discovery with ‘listAgents’, detailed agent capabilities with ‘describeAgent’, execution of agents with conflict resolution using ‘callAgent’, dynamic server addition with ‘connectServer’, and server removal with ‘disconnectServer’.

Where to use

mcp-agent-proxy can be used in various fields that require agent communication and orchestration, such as distributed systems, IoT applications, and any environment that benefits from agent-based architectures.

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:

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

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:

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.