Как дебажить MCP сервер?

MCP-сервер — это отдельный процесс. Когда он не работает, Cursor просто показывает «error» в списке серверов. Понять почему — задача разработчика.

Есть три уровня отладки: логи редактора, MCP Inspector, ручной запуск сервера.

Шаг 1: Смотри логи Cursor

Cursor Settings → MCP — здесь видно статус каждого сервера. Если «error», нажми на сервер — иногда там есть сообщение об ошибке.

Подробные логи: Help → Toggle Developer Tools → Console. Ищи строки с MCP или названием сервера.

Шаг 2: MCP Inspector

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

npx @modelcontextprotocol/inspector node /path/to/your/server/dist/index.js

Открывай http://localhost:5173. Там:

• список всех зарегистрированных инструментов
• форма для вызова каждого с нужными аргументами
• сырой JSON запроса и ответа

Это быстрее, чем каждый раз перезапускать Cursor и писать в чат.

Шаг 3: Ручной запуск и логи

Добавь логирование в сервер через stderr — stdout занят протоколом MCP, туда писать нельзя:

server.tool(
  "get_user",
  "Получает пользователя по ID",
  { userId: z.string() },
  async ({ userId }) => {
    process.stderr.write(`[get_user] вызван с userId: ${userId}\n`);

    try {
      const res = await fetch(`https://api.example.com/users/${userId}`);
      process.stderr.write(`[get_user] статус ответа: ${res.status}\n`);

      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      const user = await res.json();

      process.stderr.write(`[get_user] успех: ${JSON.stringify(user)}\n`);
      return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };
    } catch (e) {
      process.stderr.write(`[get_user] ошибка: ${e}\n`);
      return { content: [{ type: "text", text: `Ошибка: ${e}` }] };
    }
  }
);

Запусти сервер вручную и смотри stderr:

node dist/index.js 2>debug.log
# или сразу в терминал:
node dist/index.js 2>&1

Частые причины ошибок

command not found — путь к исполняемому файлу неправильный. Проверь command и args в конфиге.

Сервер запускается, но инструменты не появляются — скорее всего, исключение при старте. Смотри stderr.

spawn ENOENT — Node.js не найден или npx не в PATH. Укажи полный путь: /usr/local/bin/node вместо node.

Инструмент вызывается, но возвращает пустоту — убедись, что возвращаешь правильную структуру: { content: [{ type: "text", text: "..." }] }.