MCP¶
Манифесты инструментов для серверов Model Context Protocol. У сервера MCP, например Grav MCP Server, уже есть инструменты для всего, что делает сам плагин API, но он не может знать о маршрутах, которые другие плагины добавляют через onApiRegisterRoutes. Плагин описывает эти маршруты как инструменты — в файле mcp.yaml в своём корне или в коде через событие onApiMcpTools, а Список инструментов MCP отдаёт объединение инструментов всех включённых плагинов, чтобы сервер MCP мог зарегистрировать их при запуске без кода, написанного под каждый плагин.
Разрешения: api.access. Каждый инструмент дополнительно фильтруется по разрешению, которое он называет.
Список инструментов MCP¶
GET /mcp/tools
Все инструменты MCP, описанные включёнными плагинами, отфильтрованные до того, что вызывающая сторона может вызвать: инструмент, называющий разрешение, которого у вызывающей стороны нет, опускается, инструменты без указания разрешения включаются всегда, а суперадминистратор видит всё. Поддерживает If-None-Match: совпадающий ETag возвращает пустой 304. Требуется api.access.
Ответ
{"data": {"tools": [{"name": "kahunacart_list_products", "plugin": "kahunacart", "title": "List products", "description": "List catalog products with paging, search and status filters.", "method": "GET", "path": "/kahunacart/products", "permission": "kahunacart.products.manage", "annotations": {"readOnly": true, "destructive": false, "idempotent": true}, "input_schema": {"type": "object", "properties": {"q": {"type": "string"}}}, "path_params": [], "query": [], "body": null}], "plugins": [{"slug": "kahunacart", "name": "KahunaCart", "version": "0.1.0", "tools": 1}], "warnings": [], "fingerprint": "5f1d9c2a7b3e4d08"}}
Коды ответов
| Код | Описание |
|---|---|
200 |
Инструменты возвращены, с заголовком ETag. |
304 |
ETag из If-None-Match всё ещё совпадает; тело пустое. |
401 |
Не авторизован. |
403 |
Нет разрешения api.access. |
Каждый инструмент содержит:
| Поле | Значение |
|---|---|
name |
Имя инструмента, которое регистрирует клиент MCP: {prefix}_{name} из манифеста, не более 64 символов |
plugin |
Slug плагина, который его добавил |
title |
Человекочитаемый заголовок, который может показать клиент MCP, или null |
description |
Что делает и возвращает инструмент и когда его использовать |
method |
GET, POST, PATCH, PUT или DELETE |
path |
Путь маршрута относительно базы API; заполнители {name} заполняются из аргументов |
permission |
Разрешение, которое требует маршрут, или null |
annotations |
readOnly, destructive и idempotent, всегда заполнены значениями по умолчанию для метода |
input_schema |
Объект JSON Schema для аргументов; у инструмента без аргументов — {"type": "object", "properties": {}} |
path_params |
Заполнители {name} в path, по порядку |
query |
Для методов записи — свойства, отправляемые параметрами запроса, а не в теле (GET отправляет каждое свойство, не относящееся к пути, как параметр запроса) |
body |
Единственное свойство, значение которого является всем телом запроса, или null, когда тело собирается из остальных свойств |
plugins[].tools считает инструменты, видимые этой вызывающей стороне, а не то, сколько объявляет манифест. В warnings по одной строке на каждую пропущенную запись манифеста с причиной, например неподдерживаемое ключевое слово JSON Schema. fingerprint меняется, когда меняется набор включённых плагинов или любой файл манифеста, и он же является ETag ответа.