> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/russian/advanced-basic/extensions/mcp/troubleshooting.md).
# Устранение неполадок MCP
Проблемы с MCP обычно возникают на четырёх этапах: сервер не запущен, среда выполнения неполная, ошибка в аутентификации или адресе, либо агент не привязан. Проверяйте по порядку — это быстрее, чем переустанавливать всё снова и снова.
Проверяйте по порядку: сначала убедитесь, что сам сервер может работать, и только потом смотрите на цепочку вызовов агента.
## Быстрая проверка
| Симптом | Сначала проверьте | Распространённые причины |
| ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Сервер не запускается | 【Настройки】→【MCP】→подробности сервера→журнал | Команда не существует, ошибка параметров, отсутствуют переменные среды |
| Сбой удалённого подключения | URL, сетевой прокси, аутентификация | Неверный протокол адреса, служба недоступна, токен недействителен |
| Сервер работает нормально, но нет инструментов | Список инструментов в подробностях сервера | Служба не вернула инструменты или недостаточно прав |
| Инструменты есть, но агент их не вызывает | Агент【MCP】 | Не привязан, инструменты отключены, конфигурация не вступила в силу из следующего сообщения |
| Вызов зависает в ожидании | Запросы разрешений агента и справа【Статус】 | Требуется ручное одобрение или фоновая задача не завершена |
| Вызов возвращает ошибку | Входные данные, выходные данные и статус цепочки вызовов | Параметры не соответствуют определению инструмента, ошибка на стороне сервера |
## Порядок проверки
{% stepper %}
{% step %}
### 1. Отдельно проверьте сервер на странице настроек MCP
Убедитесь, что статус нормальный и видны инструменты, ресурсы или подсказки. Если здесь ничего нет, не настраивайте сначала агента.
{% endstep %}
{% step %}
### 2. Проверьте среду выполнения
Для локальных команд нужны соответствующая среда выполнения и исполняемый файл. Если в пути или команде есть пробелы, разделяйте команду и параметры согласно инструкции сервера; не рассматривайте всю строку конфигурации как один путь.
{% endstep %}
{% step %}
### 3. Проверьте аутентификацию и сеть
Проверьте URL, токен, прокси и сертификаты. Не отправляйте полный секрет в публичный Issue; при необходимости оставьте только несколько символов в начале и в конце для идентификации.
{% endstep %}
{% step %}
### 4. Проверьте привязку и права агента
Убедитесь, что сервер включён в【MCP】агента, и проверьте текущий режим прав. Отправьте новое минимальное тестовое задание, которое вызывает только один инструмент.
{% endstep %}
{% step %}
### 5. Используйте цепочку вызовов для определения запроса
Если всё ещё не удаётся определить причину, откройте【Настройки】→【Система】→【Режим разработчика】, перезапустите приложение и повторите проблему один раз, затем в цепочке вызовов посмотрите имя службы MCP, тип, входные данные, выходные данные и статус.
{% endstep %}
{% endstepper %}
## Пример: инструменты видны, но агент не вызывает их
Сначала в подробностях MCP подтвердите, что инструменты существуют, затем в【MCP】агента убедитесь, что они привязаны. Отправьте новое минимальное задание, которое требует вызвать только этот инструмент; если оно зависает в ожидании, проверьте подтверждение прав; если появляется узел вызова, но возвращается ошибка, смотрите параметры и журналы сервера. Не переустанавливайте сервер в самом начале.
### Критерий завершения отладки
Можно чётко определить, на каком этапе возникла проблема: «запуск сервера, подключение и аутентификация, привязка агента, подтверждение прав, выполнение инструмента», и сохранить одно минимальное тестовое задание, которое можно воспроизвести.
{% hint style="danger" %}
Перед публикацией журналов удалите API Key, Authorization, e-mail, локальное имя пользователя, полный путь к файлам и бизнес-данные. Если проблему можно описать с помощью заглушек, не загружайте реальные учётные данные.
{% endhint %}
Почему та же конфигурация работает в терминале, но не работает в Cherry Studio?
Переменные среды и PATH у процесса приложения и у вошедшего в систему терминала могут отличаться. Запишите в конфигурацию MCP те переменные среды, которые явно требуются службе, и убедитесь, что команда — это исполняемый файл, который приложение может найти.
Нужно ли удалить и заново добавить сервер?
Сначала посмотрите журнал и поочерёдно исправьте ошибки. Удалять и заново создавать сервер стоит только тогда, когда конфигурация уже запутана и источник можно получить заново; перед удалением сохраните копию конфигурации без секретов.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.cherryai.com.cn/docs/russian/advanced-basic/extensions/mcp/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.