探索 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
| Key | Value |
|---|---|
| Request Method | POST |
| accept | application/json |
| Content-Type | application/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 中有此欄位,但本端點的實際處理邏輯不會用到。
| Field | Type | Detail | Required |
|---|---|---|---|
| server_url | string | 外部 MCP server 的 URL,必須以 http:// 或 https:// 開頭。本端點會使用。 | true |
| server_label | string | MCP server 的識別名稱。schema 要求必填,但本端點不使用(discover 僅針對單一 server,不需以 label 路由)。 | true |
| authorization | string | null | 存取 MCP server 用的授權憑證;系統會將此值原樣放入連線 headers 的 Authorization。本端點會使用。 不可與 headers 中的 Authorization 同時提供。 | false |
| headers | object | null | 連線 MCP server 時附帶的自訂 HTTP headers。本端點會使用。 | false |
| type | string | 固定為 mcp。本端點不使用。 | false |
| server_description | string | null | MCP server 的描述說明。本端點不使用。 | false |
| allowed_tools | array[string] | null | 工具白名單。本端點不使用——discover 一律回傳該 server 的工具,不做過濾。若要限制暴露給模型的工具,請於 Chat Completions 的 tools 中設定。 | false |
| require_approval | string | 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
| Field | Detail |
|---|---|
| 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[]._meta | MCP 協定的擴充中繼資料,可能為 null |
tools[].execution | MCP 協定的工具執行相關設定,可能為 null |
| nextCursor | 分頁游標。若非 null,表示該 server 尚有更多工具未列出;本端點目前只回傳第一頁,且不支援帶入游標取得下一頁。 |
| _meta | MCP 協定的擴充中繼資料,可能為 null |
錯誤處理
-
Request Body 格式錯誤(例如缺少
server_label/server_url、同時提供authorization與headers.Authorization):回傳 422 Validation Error。 -
server_url不是http:///https://開頭、目標 MCP server 無法連線或不支援 Streamable HTTP:請求失敗,回傳 HTTP 500。