← server.json і маніфести клієнтів
docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/mcp-bundle/discovery.md
новий файл +41
−0
1
+
# server.json і маніфести клієнтів
2
+
3
+
Кожен ендпоінт віддає ще два види документів. Обидва захищені правилом токена для документації (`protected_doc` JsonRpcBundle), відповідають 404 так само, як сам ендпоінт, і беруть URL ендпоінта із запиту: `<prefix>[/{ver}]`.
4
+
5
+
## server.json — MCP Registry
6
+
7
+
`GET <prefix>/server.json` (або `<prefix>/v2/server.json`) — документ, який очікує [MCP Registry](https://registry.modelcontextprotocol.io) під час публікації сервера (схема `2025-12-11`). Клієнти не читають його для підключення.
8
+
9
+
```json
10
+
{
11
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
12
+
"name": "io.github.your-org/your-app",
13
+
"title": "Your App MCP Server",
14
+
"description": "Exposes Your App RPC services as MCP tools.",
15
+
"version": "v1",
16
+
"websiteUrl": "https://api.example.com",
17
+
"icons": [{"src": "https://example.com/icon.png", "mimeType": "image/png", "sizes": ["128x128"]}],
18
+
"remotes": [{"type": "streamable-http", "url": "https://api.example.com/mcp"}]
19
+
}
20
+
```
21
+
22
+
* `name`, `title`, `description`, `icons` — з `mcp_server_info` групи (з fallback поле за полем на загальне налаштування, див. [Налаштування](/docs/api/mcp-bundle/config)); незадані поля не потрапляють у документ.
23
+
* `version` — `{ver}` запиту; `websiteUrl` — схема, хост і порт запиту; `remotes[0].url` — URL ендпоінта.
24
+
25
+
## Маніфести клієнтів
26
+
27
+
`GET <prefix>/manifest/{aiName}.json` — готова конфігурація підключення. Токен лишається плейсхолдером: маніфест ніколи не містить справжнього токена. Ключ сервера в конфігурації — назва групи.
28
+
29
+
| `aiName` | Для чого | Формат |
30
+
| --- | --- | --- |
31
+
| `claude` | Claude Code (`.mcp.json`) | `{"mcpServers": {"<group>": {"type": "http", "url": "…", "headers": {"Ufo-RPC-Token": "${UFO_MCP_TOKEN}"}}}}` |
32
+
| `cursor` | Cursor (`mcp.json`) | `{"mcpServers": {"<group>": {"url": "…", "headers": {"Ufo-RPC-Token": "${env:UFO_MCP_TOKEN}"}}}}` |
33
+
| `gemini` | Gemini CLI (`settings.json`) | `{"mcpServers": {"<group>": {"httpUrl": "…", "headers": {"Ufo-RPC-Token": "<UFO_MCP_TOKEN>"}}}}` |
34
+
| `openai` | OpenAI Responses API | елемент `tools[]`: `{"type": "mcp", "server_label": "<group>", "server_url": "…", "headers": {…}, "require_approval": "always"}` |
35
+
36
+
* Claude Code і Cursor підставляють змінну оточення `UFO_MCP_TOKEN` самі.
37
+
* Gemini CLI не підставляє змінні в заголовках, а OpenAI API надсилає заголовки як є: замініть `<UFO_MCP_TOKEN>` на токен вручну або у своєму коді.
38
+
* `require_approval: "always"` для OpenAI — консервативне значення, щоб бандл не дозволяв виклики без підтвердження; змініть його за потреби.
39
+
* Назва заголовка — `ufo_json_rpc.security.token_name` (типово `Ufo-RPC-Token`).
40
+
41
+
Невідомий `aiName` відповідає 404 `{"error": "Unknown MCP client manifest \"…\"."}`. Маніфест для іншого клієнта — див. [Розширення](/docs/api/mcp-bundle/developers/extensions).