接口參考

MCP 伺服器

註冊、探測與維護你的 MCP 伺服器。

伺服器需要滿足的條件、在會話中的使用方式與排查方法，見 MCP 伺服器。

POST/v1/mcp-servers

註冊 MCP 伺服器

權限: mcp_servers:write
限流: 60 次/分鐘
成功: 201

把你的遠端 MCP 伺服器註冊到項目。平台會先連接一次（完成 MCP 握手並列出工具），通過才保存，所以地址或憑證寫錯會在這一步直接報錯。這一步最長可能等待 60 秒。

請求體

namestring必填

名稱，1–64 個小寫字母、數字和單個連字元，項目內唯一。它是工具的命名空間：Agent 看到的工具名是 mcp__<name>__<工具名>。

urlstring必填

伺服器的 Streamable HTTP 端點（通常以 /mcp 結尾），必須是 https，且必須是公網地址。路徑按原樣保存（含尾部斜線）；地址裡不能帶使用者名稱和密碼，憑證放 auth。建立後不能修改。

authobject

鑑權方式，預設 {"type": "NONE"}。{"type": "BEARER", "token": "…"} 以 Authorization: Bearer 發送；{"type": "HEADER", "name": "X-Api-Key", "value": "…"} 以自訂請求頭發送。

allowed_toolsstring[] | null

只允許 Agent 調用這些工具（伺服器端的工具名），最多 256 個，不重複，不能是空陣列；不填或 null 表示全部。名字必須在探測到的工具裡。

回應：MCP 伺服器物件

idstring

伺服器 ID，mcp_…。

namestring

名稱。

urlstring

端點地址。

authobject

只有類型；HEADER 類型帶請求頭的名字。憑證加密保存，任何接口都不會返回它。

allowed_toolsstring[] | null

白名單；null 表示全部。

toolsobject[]

探測到的工具（name、description）：最多保留 256 個，名字超過 128 字元的不保留，描述截到 500 字元。allowed_tools 之外的工具 Agent 看不到。

server_namestring | null

伺服器自報的名字。

last_probed_atstring | null

最近一次探測的時間。

last_connected_atstring | null

最近一次在輪次中連接成功的時間。每一輪連接時更新：成功記錄時間並清空錯誤，失敗記錄原因。

last_connect_errorstring | null

最近一次連接失敗的原因。排查「Agent 沒有調用我的工具」時先看這兩項。

created_atstring

建立時間。

updated_atstring

最後修改配置的時間。

錯誤

狀態碼	type	原因
422	`invalid_mcp_server_url`	不是 `https`，或主機解析到內網、本機等非公網地址。
422	`mcp_probe_failed`	探測失敗：連不上、逾時、憑證被拒（401/403）、返回的不是 MCP 協議等。`message` 說明具體情況，對照表見註冊。
422	`unknown_mcp_tool`	`allowed_tools` 裡有伺服器沒有的工具，`details` 列出。
409	`mcp_server_name_taken`	項目中已有同名伺服器。
409	`mcp_server_url_taken`	項目中已註冊了同一個地址。

請求

curl -s "$AXON_API/mcp-servers" \
  -H "Authorization: Bearer $AXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "shop",
        "url": "https://mcp.example.com/mcp",
        "auth": {"type": "BEARER", "token": "your-mcp-token"},
        "allowed_tools": ["lookup_order", "create_ticket"]
      }'

回應

{
  "id": "mcp_7d2c9e4a1b5f4c8e9a3d6f0b2c4e6a8d",
  "name": "shop",
  "url": "https://mcp.example.com/mcp",
  "auth": {"type": "BEARER", "name": null},
  "allowed_tools": ["lookup_order", "create_ticket"],
  "tools": [
    {"name": "lookup_order", "description": "Find an order by its number."},
    {"name": "create_ticket", "description": "Open a support ticket."},
    {"name": "list_products", "description": "List the catalog."}
  ],
  "server_name": "shop-mcp",
  "last_probed_at": "2026-10-10T01:12:40.204911Z",
  "last_connected_at": null,
  "last_connect_error": null,
  "created_at": "2026-10-10T01:12:40.204911Z",
  "updated_at": "2026-10-10T01:12:40.204911Z"
}

GET/v1/mcp-servers

MCP 伺服器列表

權限: mcp_servers:read
成功: 200

按建立時間從新到舊返回項目中的 MCP 伺服器，分頁方式見分頁。每個元素是 MCP 伺服器物件。

查詢參數

limitinteger

每頁條數，1–100，預設 20。

cursorstring

上一頁的 meta.next_cursor。

請求

curl -s "$AXON_API/mcp-servers" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "items": [{"id": "mcp_7d2c…", "name": "shop", "url": "https://mcp.example.com/mcp", "...": "..."}],
  "meta": {"next_cursor": null}
}

GET/v1/mcp-servers/{mcp_server_id}

查詢 MCP 伺服器

權限: mcp_servers:read
成功: 200

返回 MCP 伺服器物件。last_connect_error 是排查 Agent 沒有調用工具時的第一個線索。

路徑參數

mcp_server_idstring必填

伺服器 ID。

錯誤

狀態碼	type	原因
404	`mcp_server_not_found`	不存在、已刪除或屬於其他項目。

請求

curl -s "$AXON_API/mcp-servers/$MCP" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "id": "mcp_7d2c9e4a1b5f4c8e9a3d6f0b2c4e6a8d",
  "name": "shop",
  "url": "https://mcp.example.com/mcp",
  "auth": {"type": "BEARER", "name": null},
  "allowed_tools": ["lookup_order", "create_ticket"],
  "tools": [
    {"name": "lookup_order", "description": "Find an order by its number."},
    {"name": "create_ticket", "description": "Open a support ticket."},
    {"name": "list_products", "description": "List the catalog."}
  ],
  "server_name": "shop-mcp",
  "last_probed_at": "2026-10-10T01:12:40.204911Z",
  "last_connected_at": "2026-10-10T02:03:17.550128Z",
  "last_connect_error": null,
  "created_at": "2026-10-10T01:12:40.204911Z",
  "updated_at": "2026-10-10T01:12:40.204911Z"
}

PATCH/v1/mcp-servers/{mcp_server_id}

修改 MCP 伺服器

權限: mcp_servers:write
限流: 60 次/分鐘
成功: 200

只傳需要改的欄位，返回修改後的 MCP 伺服器物件。地址不能修改：換地址請刪除後重新註冊。

請求體

namestring

改名，工具名的命名空間隨之改變：已指定它的會話從下一輪起看到新的工具名。不能為 null。

authobject

換憑證，寫法同註冊。平台會用新憑證重新探測，不通過則不保存。不能為 null。

allowed_toolsstring[] | null

換白名單，名字必須在當前 tools 裡；傳 null 取消限制。

錯誤

狀態碼	type	原因
404	`mcp_server_not_found`	不存在、已刪除或屬於其他項目。
422	`invalid_mcp_server_url`	換憑證時重新探測，地址不再通過安全檢查。
422	`mcp_probe_failed`	用新憑證探測失敗，什麼都不保存。
422	`unknown_mcp_tool`	`allowed_tools` 裡有當前 `tools` 沒有的工具，`details` 列出。
409	`mcp_server_name_taken`	項目中已有同名伺服器。

請求

curl -s -X PATCH "$AXON_API/mcp-servers/$MCP" \
  -H "Authorization: Bearer $AXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth": {"type": "BEARER", "token": "rotated-token"}, "allowed_tools": null}'

回應

{
  "id": "mcp_7d2c9e4a1b5f4c8e9a3d6f0b2c4e6a8d",
  "name": "shop",
  "url": "https://mcp.example.com/mcp",
  "auth": {"type": "BEARER", "name": null},
  "allowed_tools": null,
  "tools": [
    {"name": "lookup_order", "description": "Find an order by its number."},
    {"name": "create_ticket", "description": "Open a support ticket."},
    {"name": "list_products", "description": "List the catalog."}
  ],
  "server_name": "shop-mcp",
  "last_probed_at": "2026-10-11T09:30:02.771004Z",
  "last_connected_at": "2026-10-10T02:03:17.550128Z",
  "last_connect_error": null,
  "created_at": "2026-10-10T01:12:40.204911Z",
  "updated_at": "2026-10-11T09:30:02.771004Z"
}

POST/v1/mcp-servers/{mcp_server_id}/probe

重新探測

權限: mcp_servers:write
限流: 60 次/分鐘
成功: 200

伺服器新增或刪除了工具後調用，刷新 tools。無請求體，返回 MCP 伺服器物件。探測失敗時已保存的資訊不變。

路徑參數

mcp_server_idstring必填

伺服器 ID。

錯誤

狀態碼	type	原因
404	`mcp_server_not_found`	不存在、已刪除或屬於其他項目。
422	`mcp_probe_failed`	探測失敗，`message` 說明原因。
422	`invalid_mcp_server_url`	地址不再通過安全檢查。

請求

curl -s -X POST "$AXON_API/mcp-servers/$MCP/probe" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "id": "mcp_7d2c9e4a1b5f4c8e9a3d6f0b2c4e6a8d",
  "name": "shop",
  "tools": [
    {"name": "lookup_order", "description": "Find an order by its number."},
    {"name": "create_ticket", "description": "Open a support ticket."},
    {"name": "list_products", "description": "List the catalog."},
    {"name": "cancel_order", "description": "Cancel an order that has not shipped."}
  ],
  "last_probed_at": "2026-10-12T06:41:55.090327Z",
  "...": "..."
}

DELETE/v1/mcp-servers/{mcp_server_id}

刪除 MCP 伺服器

權限: mcp_servers:write
限流: 60 次/分鐘
成功: 204（無回應體）

已經指定了它的會話不受影響，但從下一輪起不再連接它，Agent 不再擁有它的工具。名稱和地址可以給新註冊的伺服器使用。

路徑參數

mcp_server_idstring必填

伺服器 ID。

錯誤

狀態碼	type	原因
404	`mcp_server_not_found`	不存在、已刪除或屬於其他項目。

請求

curl -s -X DELETE "$AXON_API/mcp-servers/$MCP" -H "Authorization: Bearer $AXON_KEY"

回應

204 No Content