# 探索 MCP 工具

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

:::info[💡]

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

:::

```bash
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；其餘欄位仍會做格式驗證，但在本端點不生效（僅為格式相容而保留）。

```json
{
  "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 |

:::warning[⚠️]

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

:::

---

### Response

#### 200 OK

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

```json
{
  "_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。
