技术文档摘要

MCP代理服务器

连接任何MCP客户端到任何代理服务器——通过简单的可组合原语创建一个“代理互联网”。

支持 Mastra ❤️ 和 LangGraph 🦜🕸️ 服务器！🎉

快速开始

在您的MCP客户端配置中添加以下内容：

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

就这样！ 该代理允许您的MCP客户端连接到不同的代理服务器，并将代理交互作为MCP工具公开。它会自动检测代理服务器类型并相应地进行调整。

https://github.com/user-attachments/assets/9eaf1d36-298f-430f-b9e8-37e921cce2d1

功能概述

我们提供5个简单工具，而不是构建复杂的协议，这些工具让代理能够发现、连接并在无限网络中编排：

工具	目的
listAgents	发现所有服务器上的可用代理
describeAgent	获取详细的代理功能以实现智能路由
callAgent	执行任何代理并解决智能冲突
connectServer	在运行时动态添加新的代理服务器
disconnectServer	移除动态连接的服务器

支持的服务器类型

• Mastra：支持本地和远程的Mastra服务器
• LangGraph：支持本地和远程的LangGraph实例
• 可扩展性：插件架构使得添加对其他代理框架的支持变得容易

网络效应

代理服务器本身可以是MCP客户端，从而创建递归代理网络：

您的MCP客户端 → MCP代理 → 代理服务器（Mastra/LangGraph）→ 代理 → MCP代理 → 其他代理服务器 → 🚀 代理

一行配置即可解锁整个AI能力生态系统。

MCP合规性和特性

✅ 完全符合MCP 2025-03-26标准

• 完整实现了最新的模型上下文协议规范

🚀 多传输支持

• Stdio传输：标准MCP客户端集成（npx mcp-agent-proxy）
• 流式HTTP：基于现代HTTP的传输，具有会话管理
• 遗留SSE：与现有SSE实现的向后兼容性
• 自动检测：根据客户端能力无缝切换传输方式

常见配置

多服务器（混合类型）

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["mcp-agent-proxy"],
      "env": {
        "AGENT_SERVERS": "http://localhost:4111 http://localhost:2024"
      }
    }
  }
}

云+本地（混合Mastra和LangGraph）

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "npx",
      "args": ["mcp-agent-proxy"],
      "env": {
        "AGENT_SERVERS": "https://my-mastra.vercel.app http://localhost:2024"
      }
    }
  }
}

源码（开发）

{
  "mcpServers": {
    "mcpAgentProxy": {
      "command": "node",
      "args": ["/path/to/mcp-agent-proxy/dist/mcp-server.js"],
      "env": {
        "AGENT_SERVERS": "http://localhost:4111"
      }
    }
  }
}

使用示例

基本代理调用：

你能调用weatherAgent来获取纽约市当前的天气吗？

网络探索

探索你所连接到的代理

智能冲突解决：

我需要使用来自server1的weatherAgent，而不是默认的那个

动态网络扩展：

连接到https://ml-specialists.vercel.app上的ML专家，然后使用他们的modelTrainer代理

环境变量

变量	默认值	描述
AGENT_SERVERS	无	逗号或空格分隔的服务器URL（支持Mastra和LangGraph）
MCP_SERVER_PORT	3001	代理服务器端口
MCP_TRANSPORT	http	传输方法（stdio/http）

示例及高级用法

在examples/目录中的即用型配置：

• mcp.json - 零设置
• multi-server-config.json - 多个本地服务器
• vercel-config.json - 云端部署

对于高级配置选项，请参阅CONFIGURATION.md。

故障排除

NPX问题：

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

端口冲突：

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

连接问题：

• 确保代理服务器正在运行且可访问
• 检查防火墙设置和服务器URL
• 对于LangGraph：默认端口通常是2024（langgraph dev）
• 对于Mastra：默认端口通常是4111

调试模式：

DEBUG=mastra:* npx mcp-agent-proxy

开发与测试

验证工作流程

我们已经实现了全面的验证工作流程，以确保代码质量和MCP协议合规性：

快速命令

# 快速验证（构建 + 测试 + 代码检查 + 格式化）
pnpm validate:quick

# 完整验证（包括集成测试 + 健康检查）
pnpm validate:full

# CI验证（包括覆盖率 + 死代码分析）
pnpm validate:ci

单独命令

# 构建和测试
pnpm build
pnpm test
pnpm test:integration

# 代码质量
pnpm lint
pnpm format
pnpm format:check

MCP协议测试

# 测试MCP协议合规性
pnpm mcp:test

# 测试安全功能
pnpm security:test

# 手动服务器测试
pnpm start           # 启动开发服务器
pnpm check          # 检查运行中的服务器（需要jq）

测试覆盖率

• 355个总测试覆盖所有组件
• 单元测试针对所有工具、插件和配置
• 集成测试针对MCP协议合规性
• 安全测试针对源验证和会话管理
• 健康检查用于服务器监控

可用脚本

使用pnpm run查看所有可用脚本，或者使用以下常见脚本：

pnpm dev             # 构建并启动开发服务器
pnpm test            # 运行所有测试
pnpm test:watch      # 在监视模式下运行测试
pnpm build           # 为生产构建
pnpm lint            # 运行ESLint
pnpm format          # 使用Prettier格式化代码

贡献

我们欢迎贡献！请参阅我们的贡献指南了解详情。

许可证

MIT许可证 - 详情请参阅LICENSE文件。

---

<div align="center">

📖 配置指南 • 🚀 示例 • 🐛 问题 • 💬 讨论

一次连接，构建代理互联网。

</div>