401 Unauthorized в MCP: устранение проблем с API-ключом и заголовком авторизации

Получаете ошибки 401 Unauthorized при работе с MCP? Это целенаправленное руководство по устранению неполадок поможет исправить проблемы аутентификации: отсутствующий заголовок Authorization, неверный формат Bearer, отозванные API-ключи и проблемы с пробелами. Узнайте, как проверить свою настройку и безопасно ротировать ключи.

Что означает 401 Unauthorized

Ошибка 401 указывает на то, что ваш запрос достиг сервера, но аутентификация не удалась. Это отличается от ошибок подключения — сервер доступен, но он не распознаёт или не принимает ваши учётные данные.

Распространённые причины

Отсутствующий заголовок Authorization
Неверный формат токена Bearer
Отозванный или истёкший API-ключ
Проблемы с пробелами при копировании ключа
API-ключ привязан к неправильному рабочему пространству

Шаг 1: проверьте формат заголовка Authorization

Заголовок Authorization должен быть отформатирован именно как "Bearer " с последующим API-ключом (с одним пробелом).

Правильный формат

Правильный заголовок Authorization

Authorization: Bearer YOUR_API_KEY

Ключевые моменты:

"Bearer" (заглавная B, остальное строчными)
Один пробел после "Bearer"
Без кавычек вокруг API-ключа
Без лишних пробелов или переносов строк

Распространённые ошибки формата

Отсутствует префикс "Bearer "

Authorization: YOUR_API_KEY

Исправление: добавьте "Bearer " перед API-ключом

Неверный регистр

Authorization: bearer YOUR_API_KEY
Authorization: BEARER YOUR_API_KEY

Исправление: используйте именно "Bearer" (заглавная B, остальное строчными)

Отсутствует пробел после "Bearer"

Authorization: BearerYOUR_API_KEY

Исправление: добавьте один пробел: "Bearer YOUR_API_KEY"

Лишние пробелы

Authorization: Bearer  YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

Исправление: используйте ровно один пробел между "Bearer" и ключом, без завершающих пробелов

Шаг 2: проверьте статус API-ключа

Убедитесь, что ваш API-ключ активен и действителен:

Шаги проверки

Войдите в Workify
Перейдите в Settings → Integrations → Public API
Найдите свой API-ключ в списке
Проверьте, отображается ли он как "Active"
Убедитесь, что имя ключа совпадает с тем, что вы используете

Проблемы со статусом ключа

Отозванный ключ

Симптом: ключ отображается как "Revoked" или "Inactive" в Workify
Исправление: создайте новый API-ключ и обновите конфигурацию MCP

Истёкший ключ

Симптом: у ключа есть дата истечения, которая уже прошла
Исправление: сгенерируйте новый API-ключ (по умолчанию ключи не истекают, но проверьте, не была ли установлена дата истечения)

Неправильное рабочее пространство

Симптом: ключ существует, но принадлежит другому рабочему пространству
Исправление: убедитесь, что вы вошли в правильное рабочее пространство Workify, или создайте ключ в нужном рабочем пространстве

Шаг 3: проверьте наличие проблем с пробелами

При копировании API-ключей лишние пробелы могут вызвать сбои аутентификации:

Распространённые проблемы с пробелами

Начальные/конечные пробелы: ключ скопирован с пробелами в начале или в конце
Переносы строк: ключ разбит на несколько строк
Скрытые символы: непечатаемые символы из копирования/вставки
Множественные пробелы: лишние пробелы внутри ключа (редко, но возможно)

Как исправить проблемы с пробелами

Скопируйте API-ключ из Workify заново
Вставьте в простой текстовый редактор (не в текстовый процессор)
Вручную выделите только символы ключа (без пробелов до/после)
Скопируйте снова и вставьте в файл конфигурации
Убедитесь, что в файле конфигурации нет лишних пробелов

Проверьте в файле конфигурации

Проверьте правильность форматирования вашего файла конфигурации MCP:

Правильный формат конфигурации

{
  "mcpServers": {
    "workify": {
      "url": "https://app.workify.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Примечание: API-ключ должен идти сразу после "Bearer " без лишних пробелов или переносов строк.

Шаг 4: протестируйте аутентификацию

Проверьте настройку аутентификации с помощью curl:

Тест с curl

Базовый тест аутентификации

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.workify.ru/mcp

Ожидаемый ответ: должен вернуть 200 OK или список инструментов, а не 401 Unauthorized

Подробный тест (просмотр заголовков)

curl -v -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.workify.ru/mcp

Флаг -v показывает заголовки запроса/ответа для отладки

Интерпретация результатов

200 OK: аутентификация успешна
401 Unauthorized: аутентификация не удалась (проверьте формат заголовка и статус ключа)
403 Forbidden: ключ действителен, но не имеет разрешений (см. руководство по 403)

Шаг 5: безопасно ротируйте API-ключи

Если вам нужно создать новый API-ключ, следуйте этому безопасному процессу ротации:

Шаги безопасной ротации ключей

Создайте новый ключ: сгенерируйте новый API-ключ в Workify Settings → Integrations
Обновите конфигурацию: обновите файл конфигурации MCP новым ключом
Протестируйте новый ключ: убедитесь, что новый ключ работает с curl или вашим MCP-клиентом
Перезапустите клиент: перезапустите MCP-клиент, чтобы загрузить новую конфигурацию
Проверьте появление инструментов: подтвердите, что инструменты MCP доступны с новым ключом
Отзовите старый ключ: только после подтверждения работы нового ключа отзовите старый

Важно: не отзывайте старый ключ слишком рано

Держите старый ключ активным, пока не подтвердите работу нового ключа. Это предотвращает прерывание обслуживания, если у нового ключа возникнут проблемы.

Лучшие практики ротации ключей

Называйте ключи описательно: используйте имена вроде "Claude Desktop - MacBook Pro" для отслеживания использования
Ротируйте регулярно: установите расписание ротации ключей (например, каждые 90 дней)
Один ключ на клиент: используйте отдельные ключи для разных MCP-клиентов
Отслеживайте использование ключей: периодически просматривайте активные ключи и отзывайте неиспользуемые
Немедленно отзывайте скомпрометированные ключи: если ключ раскрыт, сразу же отзовите его

Чек-лист быстрого исправления

Перед обращением в поддержку

✅ Формат заголовка Authorization — "Bearer YOUR_API_KEY" (точный формат)
✅ API-ключ активен в Workify Settings → Integrations
✅ В API-ключе нет лишних пробелов
✅ JSON файла конфигурации валиден (см. Ошибки JSON конфигурации)
✅ Тест curl с ключом возвращает 200 OK (не 401)
✅ MCP-клиент был перезапущен после изменений конфигурации

Связанные материалы по устранению неполадок

403 Forbidden — исправление проблем с разрешениями после успешной аутентификации
Connection Failed — диагностика сетевых проблем до аутентификации
Config JSON Errors — исправление синтаксиса JSON, который ломает загрузку конфигурации
Индекс устранения неполадок — просмотр всех руководств по устранению неполадок