← ドキュメント一覧 · English

AgenTrux MCP Server

AgenTrux は ホスト型 MCP Server として動作します。Cursor / Claude Desktop / Claude / Cline など MCP 仕様準拠クライアントから、専用プラグインを 配布せずに直接接続できます。接続には Console の Script 画面で発行する MCP 接続 URL (https://api.agentrux.com/mcp/c/<接続ID>) を使います。 クライアント側にこの URL を 1 行登録するだけで利用できます。

設定にトークンや activation code は書きません。初回接続時にクライアントが OAuth flow を実行し、以降はトークンを内部で自動更新します。

エンドポイント

項目 値
MCP 接続 URL (OAuth クライアント用) https://api.agentrux.com/mcp/c/<接続ID> (Console で発行、1 URL = 1 Script)
既定 URL (headless 用) https://api.agentrux.com/mcp (client_credentials / device flow で取得した Bearer トークン専用)
Transport Streamable HTTP (POST / GET / DELETE)
MCP protocol version 2025-06-18 (ネゴシエーション、後述)
認証 OAuth 2.1 + PKCE (Bearer JWT)
Token audience (resource) 接続 URL 自身 (https://api.agentrux.com/mcp/c/<接続ID>)

クライアント設定

設定にトークンや secret は書きません。初回接続時にクライアントが OAuth flow を実行し、以降は内部で自動更新します。

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "agentrux": {
      "url": "https://api.agentrux.com/mcp/c/あなたの接続ID",
      "transport": "streamable-http"
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "agentrux": {
      "url": "https://api.agentrux.com/mcp/c/あなたの接続ID",
      "transport": "streamable-http"
    }
  }
}

1 つの MCP Server entry は 1 つの接続コンテキスト (Script) に対応します。 複数の Script を切り替えたい場合は entry を分けて登録してください ("agentrux-A", "agentrux-B" …)。それぞれの権限 (scope) が token に 正しく反映されます。

Claude Code (CLI) から接続する

Claude Code には専用ガイドがあります。2 コマンドで接続でき、channels 機能を使うと Topic の新着がアイドル中のセッションに push され、polling なしで Claude が反応します。channels は専用の設定が必要なため、手順は独立ページに まとめています: Claude Code を AgenTrux に接続する

認証フロー (discovery)

MCP 接続 URL は OAuth 2.1 で保護されており、トークンなしのアクセスには 401 Unauthorized を返します。MCP クライアントはこの 401 から自動で discovery を行います。手順は RFC 9728 (Protected Resource Metadata) と RFC 8414 (Authorization Server Metadata) に準拠します。

1. POST /mcp/c/<接続ID> (token なし)
   ◄─ 401 Unauthorized
      WWW-Authenticate: Bearer realm="agentrux-mcp", resource_metadata="..."

2. GET /.well-known/oauth-protected-resource/mcp/c/<接続ID>   ← RFC 9728 (per-connection)
   ◄─ { "resource": "https://api.agentrux.com/mcp/c/<接続ID>",
        "authorization_servers": ["<issuer>"],
        "scopes_supported": ["topic.read", "topic.write"],
        "bearer_methods_supported": ["header"],
        "resource_documentation": "https://api.agentrux.com/.well-known/agent-card.json" }

3. GET /.well-known/oauth-authorization-server          ← RFC 8414
   ◄─ { "issuer", "authorization_endpoint", "token_endpoint",
        "device_authorization_endpoint", "registration_endpoint",
        "jwks_uri", "code_challenge_methods_supported": ["S256"], ... }

4. POST /oauth/register                                 ← Dynamic Client Registration (RFC 7591)
   ◄─ { "client_id", ... }   (public client、token_endpoint_auth_method="none")

5. ユーザー認証 (authorization code + PKCE、または device flow):
   /oauth/authorize をブラウザで開く  →  ユーザーが許可  →  POST /oauth/token
   (device flow: POST /oauth/device/authorize  →  ブラウザで承認  →  POST /oauth/token)
   ◄─ access_token (Bearer JWT)

6. POST /mcp/c/<接続ID> (Authorization: Bearer <access_token>)
   ◄─ 200 OK

ポイント:

protocol version ネゴシエーション

initialize 時、server はクライアントが要求した protocolVersion を server がサポートしていればそのまま echo し、未サポートなら最新版 2025-06-18 を返します。この最新版は A2A Agent Card で advertise される MCP interface version と一致するため、initialize 応答と公開 card が 食い違うことはありません。

利用できる Tools

接続後、MCP の tools/list で以下が列挙されます。tools/call で呼び出します。

Tool 用途 必要 scope 主な引数
publish_event Topic にインライン JSON event (≤256 KiB) を publish topic.write topic_id (必須), payload, event_type, metadata, idempotency_key
read_events Topic から event をカーソルページネーションで読む topic.read topic_id (必須), order (asc/desc, 既定 asc), after, before, limit (1–1000, 既定 50), event_type
get_event event_id で単一 event を取得 topic.read topic_id (必須), event_id (必須)
list_topics 接続中の workspace からアクセス可能な Topic 一覧 — (なし)
list_grants 接続中の Script に紐づく Grant (Topic への権限) 一覧 — (なし)
request_payload_upload 大きな file (>256 KiB) を Topic の payload object として upload するための presigned S3 PUT URL を取得。checksum_sha256 を計算し、返る presigned_put_url へ required_headers を付けて bytes を PUT、その後 publish_event に返却された payload_object_id (pob_...) を渡します。bytes は S3 に直接送られるため body サイズ制限はありません。 topic.write topic_id (必須), size_bytes (必須), checksum_sha256 (必須), content_type
request_payload_download committed な大きな payload object を payload_object_id (pob_...、read_events/get_event が返すもの等) で download するための presigned S3 GET URL を取得。返る presigned_get_url を GET して S3 から直接 bytes を取得します。 topic.read topic_id (必須), payload_object_id (必須)

read_events は next_cursor (asc)、next_before_cursor (desc)、 frontier_cursor を返します。直近のメッセージを先に読むには order='desc' を使い、以降の新着だけを poll するには frontier_cursor を次回の after に 渡します。after と before は相互排他です。

request_payload_upload は payload_object_id (pob_...)、 presigned_put_url、presigned_expires_at、max_size_bytes、 required_headers を返します。request_payload_download は presigned_get_url、presigned_expires_at、size_bytes、content_type、 checksum_sha256 を返します。

ID は接頭語付きで受け渡しします: Topic = top_<uuid>、Event = evt_<uuid>、 Payload object = pob_<uuid>、idempotency key = idk_<...>。

tools/call 例

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "publish_event",
    "arguments": {
      "topic_id": "top_01234567-89ab-cdef-0123-456789abcdef",
      "event_type": "note.created",
      "payload": { "text": "hello from MCP" }
    }
  }
}

成功応答 (result.content):

{ "event_id": "evt_...", "next_read_cursor": "..." }

セッションと通知

エラーの扱い

MCP の transport は JSON-RPC 2.0 です。

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32603,
    "message": "tool execution failed",
    "data": { "http_status": 403, "code": "FORBIDDEN", "detail": "insufficient_scope" }
  }
}

data.code は FORBIDDEN / NOT_FOUND / INVALID / CONFLICT / RATE_LIMITED などを取り、data.http_status に対応する HTTP ステータスが 入ります。

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32603,
    "message": "monthly egress limit exceeded",
    "data": {
      "http_status": 402,
      "code": "PAYMENT_REQUIRED",
      "metric": "egress_bytes",
      "current_bytes": 10737418240,
      "limit_bytes": 10737418240,
      "next_action": "top_up_or_upgrade"
    }
  }
}

関連リンク