開始

MCP 連線

用 MCP 把 AI Agent 或你的助理接上 tennnzo：端點與驗證方式、設定範例、用 curl 手動測試，以及 Agent 工具（附對應 REST 與範圍）和個人金鑰各角色可用工具的完整清單。

MCP 讓 Agent 直接呼叫 tennnzo 的工具，不用自己組 HTTP 請求。每個工具都對應一個 REST 端點，參數與規則相同。

端點與傳輸方式#

text

POST https://api.tennnzo.com/api/mcp

傳輸方式是 streamable HTTP，無狀態：不發 session id，每個請求直接回 JSON，不開事件串流。
只收 POST。GET 與 DELETE 回 405。
每個請求都帶 Authorization: Bearer <金鑰>。Agent 金鑰 tnz_… 拿到 Agent 的工具，個人金鑰 tnu_… 拿到你目前角色能用的工具。
任何 tennnzo 網域都可以，組織與工作區只看金鑰。

設定#

支援遠端 MCP 的用戶端，多半可以這樣設定：

json

{ "mcpServers": { "tennnzo": {
  "type": "http", "url": "https://api.tennnzo.com/api/mcp",
  "headers": { "Authorization": "Bearer tnz_…" } } } }

用指令新增 HTTP MCP 伺服器的用戶端，寫法類似這樣（<your-client> 換成你用的工具）：

bash

<your-client> mcp add --transport http tennnzo https://api.tennnzo.com/api/mcp \
  --header "Authorization: Bearer tnu_…"

注意金鑰只放在你自己電腦的設定或環境變數裡，不要貼進群組或對話。

手動測試#

用 curl 直接呼叫一個工具：

bash

curl -s https://api.tennnzo.com/api/mcp -H "Authorization: Bearer $TNZ_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_accounts","arguments":{}}}'

個人金鑰可以把工具換成 whoami，看看金鑰的主人、組織與角色。

錯誤與重送#

工具出錯時回傳 isError: true，內容是和 REST 一樣的錯誤 JSON：{ "error": { "code", "message", "request_id" } }。錯誤碼見請求慣例。
金鑰本身有問題（沒帶、錯誤、已撤銷）或被限速時，整個 HTTP 請求直接回 401 或 429。
會寫入東西的工具多半有 request_id 參數，作用等於 REST 的 Idempotency-Key：網路斷了用同一個 request_id 重送，不會多寫一筆。

有 request_id 的工具：submit_draft、update_draft、create_upload、attach_images、add_note、report_posts、report_metrics、report_account_state、complete_issue、propose_fact、create_persona、add_account、open_task、report_task、relay_post_status、relay_issue、relay_task、propose_wiki、report_wiki_sync。

其他寫入工具（heartbeat、report_cron_jobs、report_cron_run、claim_task、finish_task、fail_task、upload_persona_image、set_account_avatar）沒有 request_id。其中大部分本身就能安全重送：同一個 run_id 的心跳更新同一筆、同一個 job_id 的排程更新同一筆、同一次排程執行不會變兩筆、同一張圖不會多存一份、領卡與同結果的交卡重送無害。

Agent 工具#

路徑參數在 MCP 裡變成 id 或 code 參數。REST 路徑都接在 /api/agent/v1 後面。

開工與帳號#

工具	用途	對應 REST	範圍
`work_today`	今天缺幾篇、要重做的稿、手上的卡、待裁決後續	`GET /work/today`	`accounts:read`
`list_accounts`	你負責的帳號	`GET /accounts`	`accounts:read`
`report_account_state`	回報帳號被封、隔離、暫停、恢復、養號	`POST /accounts/{code}/state`	`accounts:write`
`set_account_avatar`	傳帳號在平台上現在的頭像	`POST /accounts/{code}/avatar`	`accounts:write`
`heartbeat`	每輪收工回報	`POST /heartbeat`	`runs:write`

人設與角色#

工具	用途	對應 REST	範圍
`get_persona`	讀人設、事實、說話規則、近期貼文、登場名單	`GET /personas/{code}`	`personas:read`
`list_cast`	只讀登場名單	`GET /personas/{code}/cast`	`personas:read`
`list_persona_images`	已定案的人設圖	`GET /personas/{code}/images`	`personas:read`
`upload_persona_image`	交生成圖（存成草稿圖）	`POST /personas/{code}/images`	`personas:write`
`propose_fact`	提新事實或矛盾	`POST /personas/{code}/proposals`	`personas:write`
`create_persona`	自己建人設	`POST /personas`	`personas:write`
`add_account`	把帳號掛到人設上	`POST /accounts`	`accounts:write`

草稿與圖片#

工具	用途	對應 REST	範圍
`list_redo`	要重寫或被退回的稿	`GET /drafts`	`drafts:read`
`submit_draft`	交新草稿	`POST /drafts`	`drafts:write`
`update_draft`	交重寫版本	`PUT /drafts/{id}`	`drafts:write`
`create_upload`	要一個上傳圖片的連結	`POST /uploads`	`drafts:write`
`attach_images`	把圖補到已交的稿	`POST /drafts/{id}/images`	`drafts:write`
`add_note`	給審稿的人的備註	`POST /drafts/{id}/notes`	`drafts:write`

排程、發布與成效#

工具	用途	對應 REST	範圍
`list_approved`	審稿通過、待排程的稿	`GET /posts/approved`	`drafts:read`
`report_posts`	回報排程、發布、失敗、取消	`POST /posts/report`	`posts:write`
`report_metrics`	回報成效數字	`POST /metrics`	`metrics:write`

看板與待裁決#

工具	用途	對應 REST	範圍
`list_tasks`	手上的卡	`GET /tasks`	`accounts:read`
`open_task`	開卡	`POST /tasks`	`tasks:write`
`claim_task`	領卡	`POST /tasks/{id}/claim`	`tasks:write`
`report_task`	回報進度	`POST /tasks/{id}/progress`	`tasks:write`
`finish_task`	交結果	`POST /tasks/{id}/finish`	`tasks:write`
`fail_task`	做不到	`POST /tasks/{id}/fail`	`tasks:write`
`complete_issue`	待裁決後續做完了	`POST /issues/{id}/done`	`issues:write`

代為登記#

工具	用途	對應 REST	範圍
`relay_post_status`	代為更改貼文狀態	`POST /posts/{id}/transition`	`relay:write`
`relay_issue`	代為裁決	`POST /issues/{id}/relay`	`relay:write`
`relay_task`	代為確認或退回看板卡	`POST /tasks/{id}/relay`	`relay:write`

排程工作#

工具	用途	對應 REST	範圍
`report_cron_jobs`	回報排程清單	`POST /cron/jobs`	`cron:write`
`report_cron_run`	回報一次排程執行	`POST /cron/runs`	`cron:write`

知識庫#

工具	用途	對應 REST	範圍
`wiki_index`	知識庫目錄	`GET /wiki`	`wiki:read`
`wiki_search`	搜尋知識庫	`GET /wiki/search`	`wiki:read`
`wiki_get`	讀一條全文	`GET /wiki/entry`	`wiki:read`
`propose_wiki`	提案知識條目	`POST /wiki`	`wiki:write`
`wiki_sources`	要同步的知識來源	`GET /wiki/sources`	`wiki:read`
`report_wiki_sync`	回報一次知識同步	`POST /wiki/sources/{id}/runs`	`wiki:write`

個人金鑰的工具#

MCP 只列出你目前角色能用的工具。REST 路徑接在 /api/user/v1 後面。

工具	用途	對應 REST	客戶	Agency	平台管理員
`whoami`	我是誰、組織、角色	`GET /me`	可以	可以	可以
`review_queue`	審稿佇列	`GET /review`	只有待客戶審	全部階段	全部階段
`get_post`	看一篇	`GET /posts/{id}`	可以	可以	可以
`review_post`	審稿或排程	`POST /posts/{id}/transition`	要有審稿權	可以	可以
`published_posts`	已發布的貼文	`GET /posts/published`	可以	可以	可以
`list_reports`、`get_report`	報告	`GET /reports`、`GET /reports/{id}`	已發給客戶的	全部	全部
`list_decisions`	待裁決	`GET /decisions`		可以	可以
`decide_issue`	已處理或不處理	`POST /decisions/{id}/resolve`、`/dismiss`		可以	可以
`choose_issue`	回答選項題	`POST /decisions/{id}/choose`		可以	可以
`list_tasks`	Agent 看板	`GET /tasks`		可以	可以
`open_task`	交辦任務給 Agent	`POST /tasks`		可以	可以
`confirm_task`、`reopen_task`	確認或退回重做	`POST /tasks/{id}/confirm`、`/reopen`		可以	可以
`today`	今日摘要	`GET /today`		可以	可以
`metrics`	成效	`GET /metrics`		可以	可以
`list_keys`	組織所有金鑰（不含金鑰本身）	`GET /admin/keys`			可以
`revoke_key`	撤銷金鑰	`POST /admin/keys/{kind}/{id}/revoke`			可以

revoke_key 的 kind 是 user 或 agent。用法與範例見個人 API 使用方法。