怎麼呼叫
連上之後，你的 agent 看到的是三支工具。各地區與各資料集不是幾百個工具，而是 execute_tool 的 tool_id 參數——所以我們新增地區，不會讓你的 context 變長。
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 兩個鍵，其餘全部放進 arguments 裡。把參數平放在外層是最常見的錯誤。
上面那個 dataset_id 從哪來？資料目錄每個地區頁都列著。兩頁的分工是：那邊給資料的身分，這邊給用法。
curl（streamable-http transport）
步驟 1：initialize 以取得 session id（位於 response header 的 mcp-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} }}}'
Response 採用 SSE‑style framing——請尋找以 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())
Tool 回傳 CallToolResult.content[0].text，內容為 JSON string。licence、citation 等 metadata 會透過 _meta 欄位透傳。
Tools reference
| Tool | Arguments | 回傳值（簡） |
|---|---|---|
| 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/ 回的全部。各地區、各資料集該用哪一支，交給 discover_tools 判斷；inspect_tool 會給你那一支的完整 JSON Schema 與計費。
Authentication
- Bearer token——header 設定為
Authorization: Bearer sk-...。這是 Twinkle Hub 發行的 virtual key，每位 user 專屬。Key 請至 /dashboard 取得。 - 無 OAuth flow——客戶端無需 PKCE 或 refresh token，僅需一支 long‑lived bearer。
- Rate limit——依方案的滾動 credits 額度控管，不是 USD 預算，也不是 per‑key RPM/TPM。各方案的數字見定價頁。
計費
免費額度、速率限制與各方案差異都整理在定價頁。額度用盡時 gateway 會先攔下呼叫，回補後自動恢復，不需要做任何設定。