呼び出し方
接続すると、エージェントに見えるのは 3 つのツールです。地域やデータセットは数百のツールではなく execute_tool の tool_id 引数——地域を追加してもコンテキストは増えません。
discover_tools欲しいデータを自然言語で書くと、該当する tool_id が返ります。inspect_tool引数の渡し方に迷ったら、まず完全な定義と課金を確認します。execute_tool実行します。課金・権限・レート制限は従来どおりです。
外側は必ずこの形
execute_tool
execute_tool({ tool_id: "tw_query_dataset", arguments: { dataset_id: "pcc-tender", filters: [{ field: "agency", operator: "contains", value: "交通部" }], limit: 10 } })
外側のキーはtool_id と arguments の 2 つだけ。残りはすべて arguments の中へ——引数を外側に並べてしまうのが最も多い誤りです。
その dataset_id はどこから？データカタログの各地域ページに載っています。あちらはデータの身元、こちらは使い方という分担です。
curl（streamable-http トランスポート）
ステップ 1：initialize して mcp-session-id レスポンスヘッダーから session id を取得
bash
curl -i -X POST https://api.twinkleai.tw/mcp/ \ -H "Authorization: Bearer sk-..." \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
ステップ 2：tools/call
bash
curl -X POST https://api.twinkleai.tw/mcp/ \ -H "Authorization: Bearer sk-..." \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -H "mcp-session-id: <from-step-1>" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{ "name":"execute_tool", "arguments":{ "tool_id":"tw_search_datasets", "arguments":{"query":"空氣品質","limit":5} }}}'
レスポンスは SSE スタイルのフレーミング — data: で始まる最後の行を見つけて JSON をパース。
Python（fastmcp）
python
import asyncio from fastmcp.client import Client from fastmcp.client.auth import BearerAuth async def main(): async with Client( "https://api.twinkleai.tw/mcp/", auth=BearerAuth("sk-..."), ) as client: tools = await client.list_tools() print([t.name for t in tools]) # 外層一定是 execute_tool，tool_id 與 arguments 兩個鍵 r = await client.call_tool( "execute_tool", { "tool_id": "tw_query_dataset", "arguments": { "dataset_id": "pcc-tender", "filters": [ {"field": "agency", "operator": "contains", "value": "交通部"} ], "limit": 10, }, }, ) # response 在 r.content[0].text — JSON string import json print(json.loads(r.content[0].text)) asyncio.run(main())
ツールは CallToolResult.content[0].text を JSON 文字列として返します。ライセンス、引用、その他のメタデータは _meta フィールドで透過。
ツールリファレンス
| ツール | 引数 | 戻り値（簡潔） |
|---|---|---|
| discover_tools | {query, country?, cursor?} | [{tool_id, name, description, access}] |
| inspect_tool | {tool_id} | {input_schema, how_to_call, execution_policy} |
| execute_tool | {tool_id, arguments} | {tool_id, result, _meta.opendata.license} |
tools/ が返すのはこの 3 つだけです。地域やデータセットごとにどれを使うかは discover_tools が判断し、inspect_tool がそのツールの完全な JSON Schema と課金を返します。
認証
- Bearer トークン — ヘッダー
Authorization: Bearer sk-...。Twinkle Hub 発行の仮想キー、ユーザー 1 人につき 1 つ。/dashboard から取得してください。 - OAuth フローなし — PKCE / リフレッシュトークン不要；長期 bearer 一本。
- レート制限 — プランごとのローリング方式 credits 枠で制御されます。USD 予算やキーごとの RPM/TPM ではありません。各プランの数値は料金ページをご覧ください。
料金
無料枠・レート制限・各プランの違いは料金ページにまとめています。枠を使い切ると gateway は回復するまで呼び出しを止め、回復後は自動で再開します。設定の変更は不要です。