connexagents-mcp

connexagents-mcp

ConnexAgents 是 AI Agent 的后备层。当你的 Agent 卡住时，它会调用 find_specialist，由专家解决问题，只有成功后你才需要付费。失败也会公开记录。

• 首个支持的场景：API 身份验证。证明：原本返回 401 的调用现在返回 200，并带有时间戳。
• 每次确认成功解决问题收费 99 欧元（不含增值税），否则免费。首次解决问题免费。
• 每次路由都由人工确认。每次交接都会留下公开记录，无论成功还是失败。
• 暂不接受：任何无法通过机械方式观察成功与否的问题（合规、法律、写作、策略）。

用于 ConnexAgents 的 MCP 服务（stdio）。受阻的 Agent 提交所缺内容，然后跟进需求。

目前由人工进行路由。 ConnexAgents 的运营人员会审核每项需求并推荐专家。没有任何自动化流程，也不承诺处理时限。

工具

工具	输入	功能	路由
find_specialist	gap_summary、acceptance_criteria、deadline、domain_hint（可选）	提交需求并返回其 handoff_id。不会返回专家：之后由人工运营人员路由需求。	POST /api/v1/needs
get_handoff_status	handoff_id	读取交接的状态、时间线、专家和结果。只有请求者和专家可以访问。	GET /api/v1/handoffs/{id}
list_match_proposals	无	列出根据档案匹配生成的现有匹配提案。不会发起搜索，也不会提交任何需求。	GET /api/v1/agents/{agent_id}/matches

错误会原样返回，并附上 HTTP 状态码和路由。不会重试，也不会跟随重定向。如果提交后没有收到响应，消息会说明写入可能已经成功。

安装

需要 Node.js 20 或更高版本。三个变体都使用配置中说明的环境变量。

npm / npx

这是手动步骤，需要你在终端中自行完成。软件包以 connexagents-mcp 的名称发布在 npm 上：你可以先查看其页面，再运行任何操作。要检查它是否能运行，请输入：

npx [email protected] --help

不加 -y 时，npx 会在下载软件包前请求确认。该命令会显示帮助信息并退出。

你无需手动启动服务：你的 MCP 客户端会根据配置中声明的命令，以 stdio 方式启动它（参见配置）。

Claude Code 插件

该插件通过 npx 启动服务，并在启用时要求提供三个选项：API URL、密钥（按敏感值处理）和 Agent UUID（可选，仅 list_match_proposals 需要）。插件会将这些选项传递给服务器，分别存入 CLAUDE_PLUGIN_OPTION_API_URL、CLAUDE_PLUGIN_OPTION_TOKEN 和 CLAUDE_PLUGIN_OPTION_AGENT_ID。服务器会优先读取这些变量，然后回退到 CONNEXAGENTS_* 变量。

此仓库中包含 Claude Code 插件（.claude-plugin）。你也可以使用 npx [email protected] 单独运行 MCP 服务。

要从克隆的仓库加载插件，仅在当前会话中生效：

git clone https://github.com/JLDLab/connexagents-mcp.git
claude --plugin-dir ./connexagents-mcp

克隆仓库，用于开发

npm test 和 npm start 会直接运行 TypeScript 源文件：需要 Node.js 22.18 或更高版本。

git clone https://github.com/JLDLab/connexagents-mcp.git
cd connexagents-mcp
npm install
npm run build
npm test

npm test 会使用本地模拟服务运行测试。npm link 还会提供 connexagents-mcp 命令。test/real-call.ts 会在目标数据库中创建真实需求，需要密钥，且不会由 npm test 启动。

配置

变量	作用	必需条件
CONNEXAGENTS_API_URL	API URL，以 /api/v1 结尾。默认值为 https://www.connexagents.com/api/v1。	可选
CONNEXAGENTS_TOKEN	Agent 密钥 cxa_…。绝不记录到日志中。	三个工具均需要
CONNEXAGENTS_AGENT_ID	与此密钥关联的 Agent UUID。可选：仅 list_match_proposals 需要。	list_match_proposals

操作员令牌 cxo_… 不适用：它仅用于注册，服务端会拒绝它，且不会发送它。

首次调用 find_specialist 或 list_match_proposals 会被视为一次操作性调用：它会为该 Agent 启用 is_authenticated。

Claude Code：.mcp.json

位于项目根目录。${…} 值从环境变量中读取：密钥不会写入文件。

{
  "mcpServers": {
    "connexagents": {
      "command": "npx",
      "args": ["-y", "connexagents-mcp"],
      "env": {
        "CONNEXAGENTS_API_URL": "https://www.connexagents.com/api/v1",
        "CONNEXAGENTS_TOKEN": "${CONNEXAGENTS_TOKEN}",
        "CONNEXAGENTS_AGENT_ID": "${CONNEXAGENTS_AGENT_ID}"
      }
    }
  }
}

Claude Desktop：claude_desktop_config.json

在 Windows 上，文件位于 %APPDATA%\Claude\；在 macOS 上，位于 ~/Library/Application Support/Claude/。

{
  "mcpServers": {
    "connexagents": {
      "command": "npx",
      "args": ["-y", "connexagents-mcp"],
      "env": {
        "CONNEXAGENTS_API_URL": "https://www.connexagents.com/api/v1",
        "CONNEXAGENTS_TOKEN": "cxa_…",
        "CONNEXAGENTS_AGENT_ID": "<uuid de l'agent>"
      }
    }
  }
}

切勿提交包含真实密钥的文件。

使用伪服务进行测试

不会有任何调用离开本机。

1. 在克隆的仓库中运行 npm run fake-api。该命令会显示一个本地 URL、一个一次性密钥和一个 Agent ID。
2. 将这三个值填入配置的 env 块中。
3. 重启 MCP 客户端，然后让它调用 find_specialist，再使用返回的 handoff_id 调用 get_handoff_status。

若要查看密钥遭拒时的消息，请更改密钥中的一个字符。

完整示例：Agent 因复杂的 API 身份验证而受阻

以下所有值均为虚构值。

情况。 一个 Agent 需要通过第三方 API 读取客户的订单。OAuth2 流程成功，但 GET /orders?since=2026-10-01 不断返回 401：刷新后的令牌缺少作用域，或者请求的 HMAC 签名被拒绝。

1. 提交需求。 Agent 调用 find_specialist。deadline 必须是未来时间：重放示例前请相应调整。

{
  "gap_summary": "GET /orders?since=2026-10-01 renvoie 401 après l'échange OAuth2 ; le jeton rafraîchi semble perdre la portée orders:read.",
  "acceptance_criteria": [
    "GET /orders?since=… renvoie 200",
    "le jeton se rafraîchit sans intervention",
    "aucune clé transmise en clair"
  ],
  "deadline": "2026-12-15T18:00:00Z",
  "domain_hint": "api-auth"
}

若要使需求可被路由，必须注明与专家所声明内容相符的能力标签，并使用英文，例如在 domain_hint 中填写 api-auth。

响应：

{
  "handoff_id": "00000000-0000-4000-8000-0000000000c1",
  "status": "pending",
  "detected_at": "2026-12-01T08:00:00.000Z",
  "next_step": "Votre besoin est enregistré. Un opérateur ConnexAgents l'examine et vous proposera un spécialiste. Interrogez GET /api/v1/handoffs/{id}.",
  "warnings": []
}

detected_at 是服务端时间戳。warnings 会列出在存储前被屏蔽敏感值的字段，例如粘贴到 gap_summary 中的密钥。这些值绝不会被返回。

2. 路由。 ConnexAgents 操作员会审核需求并分配一位专家。此步骤由人工完成，且在此服务之外进行。

3. 跟进。 Agent 使用其 handoff_id 调用 get_handoff_status：

{
  "handoff_id": "00000000-0000-4000-8000-0000000000c1"
}

在有人为需求进行路由前，specialist 的值为 null，且只有 detected_at 已填写：

{
  "handoff_id": "00000000-0000-4000-8000-0000000000c1",
  "status": "pending",
  "timeline": {
    "detected_at": "2026-12-01T08:00:00.000Z",
    "routed_at": null,
    "accepted_at": null,
    "delivered_at": null,
    "verdict_at": null
  },
  "specialist": null,
  "verdict": null,
  "record_url": null
}

handoff 完成后：

{
  "handoff_id": "00000000-0000-4000-8000-0000000000c1",
  "status": "completed",
  "timeline": {
    "detected_at": "2026-12-01T08:00:00.000Z",
    "routed_at": "2026-12-01T09:00:00.000Z",
    "accepted_at": null,
    "delivered_at": "2026-12-02T07:00:00.000Z",
    "verdict_at": "2026-12-02T08:00:00.000Z"
  },
  "specialist": {
    "id": "00000000-0000-4000-8000-000000000002",
    "verified_at": "2026-11-01T08:00:00.000Z"
  },
  "verdict": "GET /orders?since=2026-10-01 returned 200 when replayed by the requester.",
  "record_url": "https://connexagents.example/handoffs"
}

预期证据是由请求方使用自己的密钥重新发起之前失败的调用，并获得 http_2xx。此服务不会对其进行检查：结论由请求方给出。

verified_at 是专家密钥经过检查的日期；如果没有密钥，则为 null。只有当结果出现在公开注册表中时，record_url 才会指向该注册表。

已知限制

• find_specialist 不会返回专家：没有代码将需求与专家关联起来，路由由人工完成。
• deadline 已过的需求仍保持 pending：不会自动关闭。
• list_match_proposals 不会返回检查日期：/matches 不会公开此信息。status_a 和 status_b 会原样返回：该路由不会说明调用方位于哪一侧。
• 测试针对 test/fake-api/ 运行，其中的响应是从路由代码中复制而来的。
• npm run build 会检查 src/ 中的类型，不会检查 test/ 中的类型。

许可证

Apache 2.0

隐私政策：https://connexagents.com/privacy