跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

探索 MCP 工具

此 API 用於連線至指定的外部 MCP server,並列出該 server 目前提供的工具(tools)。常用於在設定 Chat Completions 的 tools 之前,先預覽某個 MCP server 提供哪些工具,或取得工具的正確名稱以便填入 allowed_tools。

💡

本端點僅支援 remote MCP / MCP connector,也就是透過 Streamable HTTP(HTTP URL) 連接的外部 MCP server。一次僅針對單一 MCP server 進行探索。

curl -X 'POST' \
'http://127.0.0.1:8000/v1/mcp/tools/discover' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"server_label": "deepwiki",
"server_url": "https://example-mcp-server.com/mcp"
}'

Request Headers​

KeyValue
Request MethodPOST
acceptapplication/json
Content-Typeapplication/json

此端點目前不需要 PrivAI 的 Authorization header(不需 API Key)。若目標 MCP server 本身需要授權,請透過 Request Body 的 authorization 或 headers 欄位帶入。


Request Body​

此端點沿用 Chat Completions tools 的 MCP Tool 定義格式,但實際只會使用 server_url、headers、authorization 來連線目標 MCP server;其餘欄位仍會做格式驗證,但在本端點不生效(僅為格式相容而保留)。

{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://example-mcp-server.com/mcp",
"authorization": "Bearer <mcp-server-token>",
"headers": {}
}

欄位說明​

下表中「本端點不使用」是指 schema 中有此欄位,但本端點的實際處理邏輯不會用到。

FieldTypeDetailRequired
server_urlstring外部 MCP server 的 URL,必須以 http:// 或 https:// 開頭。本端點會使用。true
server_labelstringMCP server 的識別名稱。schema 要求必填,但本端點不使用(discover 僅針對單一 server,不需以 label 路由)。true
authorizationstring | null存取 MCP server 用的授權憑證;系統會將此值原樣放入連線 headers 的 Authorization。本端點會使用。 不可與 headers 中的 Authorization 同時提供。false
headersobject | null連線 MCP server 時附帶的自訂 HTTP headers。本端點會使用。false
typestring固定為 mcp。本端點不使用。false
server_descriptionstring | nullMCP server 的描述說明。本端點不使用。false
allowed_toolsarray[string] | null工具白名單。本端點不使用——discover 一律回傳該 server 的工具,不做過濾。若要限制暴露給模型的工具,請於 Chat Completions 的 tools 中設定。false
require_approvalstring | null工具呼叫是否需要額外核准;目前僅可為 never。本端點不使用。false
⚠️

注意:authorization 與 headers 中的 Authorization 不可同時提供。兩者擇一即可;同時帶入會回傳 422 Validation Error。


Response​

200 OK​

回傳目標 MCP server 依 MCP 協定回傳的 tools/list 結果。tools 為該 server 提供的工具列表;實際欄位內容會依該 server 而定。

{
"_meta": null,
"nextCursor": null,
"tools": [
{
"name": "read_wiki_structure",
"title": "Read Wiki Structure",
"description": "Get a list of documentation topics for a GitHub repository.",
"inputSchema": {
"type": "object",
"properties": {
"repoName": {
"type": "string",
"description": "GitHub repository: owner/repo"
}
},
"required": ["repoName"]
},
"outputSchema": null,
"icons": null,
"annotations": null,
"_meta": null,
"execution": null
}
]
}

Field Explanation

FieldDetail
tools[]該 MCP server 提供的工具列表
tools[].name工具的程式名稱;即 Chat Completions allowed_tools 應填入的值
tools[].title工具的顯示名稱(供 UI 使用),可能為 null
tools[].description工具的說明文字,可能為 null
tools[].inputSchema描述工具參數的 JSON Schema 物件
tools[].outputSchema描述工具輸出結構的 JSON Schema 物件,可能為 null
tools[].icons工具的 icon 列表,可能為 null
tools[].annotations工具的附加提示(如 readOnlyHint、destructiveHint、idempotentHint、openWorldHint 等),可能為 null
tools[]._metaMCP 協定的擴充中繼資料,可能為 null
tools[].executionMCP 協定的工具執行相關設定,可能為 null
nextCursor分頁游標。若非 null,表示該 server 尚有更多工具未列出;本端點目前只回傳第一頁,且不支援帶入游標取得下一頁。
_metaMCP 協定的擴充中繼資料,可能為 null

錯誤處理​

  • Request Body 格式錯誤(例如缺少 server_label / server_url、同時提供 authorization 與 headers.Authorization):回傳 422 Validation Error。

  • server_url 不是 http:// / https:// 開頭、目標 MCP server 無法連線或不支援 Streamable HTTP:請求失敗,回傳 HTTP 500。