Ограничение доступа (scope)

По умолчанию AI-ассистенту доступны все инструменты MCP сервера, включая изменение и удаление ресурсов. Набор инструментов можно ограничить — это полезно, когда ассистенту нельзя доверять опасные операции:

• режим «только чтение» для диагностики и анализа;
• работа только с одной сущностью (например, контейнерами);
• запрет удаления при разрешённых изменениях;
• явный список из нескольких инструментов для узкой автоматизации.

Ограничение действует и на список инструментов (скрытые tools не видны модели), и на их вызов (вызов скрытого tool отклоняется с ошибкой), поэтому обойти его со стороны клиента нельзя.

Способы передачи ограничений

Приоритет: если заголовок установлен, соответствующий query-параметр игнорируется. Можно комбинировать: tools из заголовка + scope из query (или наоборот). Если ничего не передано — доступны все инструменты.

X-MCP-Scope: скопы по группам

Инструменты объединены в группы (toolsets) по сущностям платформы — имя группы совпадает с общим префиксом её инструментов: container_list, container_get → группа container. Полный состав групп смотрите в разделе Инструменты (tools).

Для каждой группы можно разрешить категории операций: read (чтение), write (создание и изменение), delete (удаление).

Формат значения — записи через запятую, категории внутри одной группы разделяются | или +:

X-MCP-Tools: явный список инструментов

Значение — имена tools через запятую. Подходит для узкой автоматизации, когда нужны два-три конкретных инструмента:

X-MCP-Tools: container_list,container_get,container_logs

Имена всех инструментов смотрите в разделе Инструменты (tools).

Особенности

• Регистр и пробелы вокруг значений не учитываются.
• Неизвестные группы, имена tools и некорректные категории молча игнорируются.
• Пустые заголовки приравниваются к отсутствующим — полный доступ.
• Ограничение действует на каждый HTTP-запрос и может меняться между запросами одной сессии.

Примеры

Только чтение всех ресурсов:

curl -X POST https://mcp.dockhost.io/mcp \
  -H "Authorization: Bearer <DOCKHOST_API_TOKEN>" \
  -H "X-MCP-Scope: *:read" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Контейнеры без удаления + чтение репозиториев:

curl -X POST https://mcp.dockhost.io/mcp \
  -H "Authorization: Bearer <DOCKHOST_API_TOKEN>" \
  -H "X-MCP-Scope: container:read|write,repository:read" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

То же через query-параметры (для клиентов без поддержки заголовков):

curl -X POST "https://mcp.dockhost.io/mcp?scope=*:read" \
  -H "Authorization: Bearer <DOCKHOST_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Пример конфигурации клиента с ограничением (Claude Desktop, режим «только чтение»):

{
    "mcpServers": {
        "dockhost": {
            "url": "https://mcp.dockhost.io",
            "headers": {
                "Authorization": "Bearer <DOCKHOST_API_TOKEN>",
                "X-MCP-Scope": "*:read"
            }
        }
    }
}