connexagents-mcp

connexagents-mcp

ConnexAgents は AI エージェントのためのフォールバックレイヤーです。エージェントが行き詰まったら find_specialist を呼び出し、専門家が解決します。成功した場合にのみ料金が発生します。失敗も公開されます。

• 最初にサポートするケース：API 認証。証明：401 を返した呼び出しが 200 を返すようになり、タイムスタンプが記録されます。
• 解決が証明された場合は VAT 別で 99 ユーロ、そうでなければ 0 ユーロです。最初の解決は無料です。
• ルーティングは毎回人間が確認します。引き継ぎはすべて、成功・失敗を問わず公開記録に残ります。
• 現時点では対象外：成功を機械的に確認できないあらゆる問題（コンプライアンス、法務、文章作成、戦略）。

ConnexAgents 用の stdio MCP サーバーです。行き詰まったエージェントが不足しているものを提示し、その要求の進捗を確認できます。

現在、ルーティングは人が行っています。 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 以降が必要です。3 つの方法で使用する変数については、設定を参照してください。

npm / npx

手動で行う手順です。ご自身でターミナルから実行してください。パッケージは npm に connexagents-mcp という名前で公開されています。実行する前にパッケージのページを確認できます。実行を確認するには、次のように入力します。

npx [email protected] --help

-y を指定しない場合、npx はパッケージをダウンロードする前に確認を求めます。このコマンドはヘルプを表示して終了します。

サーバーを手動で起動する必要はありません。MCP クライアントが設定に記述されたコマンドを使って、stdio でサーバーを起動します（設定を参照）。

Claude Code プラグイン

プラグインは npx 経由でサーバーを起動し、有効化時に 3 つのオプションを求めます。API URL、機密値として扱われるキー、そしてエージェントの UUID（任意。ただし list_match_proposals には必須）です。これらは CLAUDE_PLUGIN_OPTION_API_URL、CLAUDE_PLUGIN_OPTION_TOKEN、CLAUDE_PLUGIN_OPTION_AGENT_ID としてサーバーに渡されます。サーバーはまずこれらの変数を読み取り、設定されていない場合は CONNEXAGENTS_* 変数を使用します。

このリポジトリには Claude Code プラグイン（.claude-plugin）が含まれています。MCP サーバーは npx [email protected] で単独でも実行できます。

クローンからセッション中に読み込むには、次のようにします。

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/v1 で終わる API の URL。デフォルトは https://www.connexagents.com/api/v1 です。	任意
CONNEXAGENTS_TOKEN	エージェントキー cxa_…。ログに記録されることはありません。	3 つのツールすべて
CONNEXAGENTS_AGENT_ID	このキーに紐づくエージェントの UUID。任意ですが、list_match_proposals にのみ必要です。	list_match_proposals

オペレータートークン cxo_… は使用できません。これは登録にのみ使用され、サーバーは送信することなく拒否します。

find_specialist または list_match_proposals の最初の呼び出しは、運用上の呼び出しとしてカウントされ、エージェントの 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、使い捨てキー、エージェント ID が表示されます。
2. 表示された 3 つの値を、設定の env ブロックに入力します。
3. MCP クライアントを再起動し、find_specialist を呼び出すよう指示してから、返された handoff_id を使って get_handoff_status を呼び出すよう指示します。

拒否されたキーのメッセージを確認するには、キーの文字を 1 つ変更します。

完全な例：複雑な認証を必要とする API で行き詰まったエージェント

以下の値はすべて架空のものです。

状況。 エージェントはサードパーティー API を介して、クライアントの注文を読み取る必要があります。OAuth2 のやり取りは成功しますが、GET /orders?since=2026-10-01 が繰り返し 401 を返します。原因として、更新されたトークンにスコープが不足しているか、リクエストの HMAC 署名が拒否されている可能性があります。

1. 必要事項の提出。 エージェントが 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. 追跡。 エージェントが自身の 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_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