В первом режиме Context7 для агента - это две консольные команды и инструкция, когда их запускать. Во втором - два инструмента, которые клиент видит в списке доступных.

Функционально режимы решают одну задачу, поэтому выбирают по среде, а не по возможностям. Если ваш агент и так живёт в терминале, скил с командной строкой ставится проще. Если клиент умеет MCP и вы уже держите там пару серверов, второй режим ровнее ложится в существующую настройку.

Установка одной командой

Ставится всё одной командой. Командной строке нужен Node.js 18 или новее.

Что происходит дальше, README описывает так: команда проходит аутентификацию через OAuth, генерирует API-ключ и ставит подходящий скил. По ходу она спрашивает, какой режим вам нужен - CLI + Skills или MCP.

Если агент известен заранее, его можно указать флагом и не отвечать на вопросы:

Убрать всё, что команда наделала, можно так же одной строкой:

Одна тонкость, которую README оговаривает отдельно: если вы ставили командную строку глобально, remove её не удалит - пакет убирается отдельно.

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

Ручная настройка, если setup не подходит

Автоматическая установка поддерживает не всё, поэтому полезно знать, что она делает руками.

Самый простой путь - удалённый сервер. Локальный Node.js для него не нужен вовсе:

Второй путь - локальный запуск через npx. Ключ при этом удобнее держать в переменной окружения, а не в аргументах:

У самого сервера три флага, и все три описаны в руководстве разработчика.

Приоритет между флагом и переменной задан явно: --api-key перебивает CONTEXT7_API_KEY, если заданы оба. Это ровно тот случай, когда стоит помнить правило заранее - иначе полдня уходит на выяснение, почему ключ из .env игнорируется.

Версии командной строки и MCP-сервера живут отдельно и по-разному. Требования к Node.js у них тоже разные: командной строке хватает 18, MCP-серверу нужен минимум 20.18.1. Если ставите не через setup, эту границу стоит проверить до того, как начнёте разбираться с загадочными ошибками модулей.

Как агент этим пользуется: два инструмента

В режиме MCP агент видит ровно два инструмента, и порядок их вызова жёстко задан.

Первый - resolve-library-id. Он превращает человеческое название библиотеки в идентификатор Context7. Принимает два обязательных аргумента: libraryName - название, и query - что именно нужно найти. Второй аргумент не декоративный: по нему результаты ранжируются, поэтому "next.js" плюс "middleware для проверки JWT" даёт более осмысленный список, чем просто "next.js".

Возвращает он не один ответ, а список кандидатов, и у каждого - набор признаков, по которым выбирают:

• Library ID - идентификатор в формате /org/project
• Name и Description - название и краткое описание
• Code Snippets - сколько в индексе примеров кода
• Source Reputation - авторитетность источника: High, Medium, Low или Unknown
• Benchmark Score - оценка качества, где 100 - максимум
• Versions - список версий, если они есть

Второй инструмент - query-docs. Он принимает выбранный libraryId и query и возвращает документацию. Вызывать его без первого шага можно только в одном случае: если пользователь сам написал идентификатор в формате /org/project.

Обе схемы содержат одно и то же ограничение, записанное капслоком в описании инструмента: не вызывать больше трёх раз на один вопрос. Формулировка у resolve-library-id прямая: "If you cannot find what you need after 3 calls, use the best result you have." Это защита от цикла, в котором агент бесконечно уточняет запрос и жжёт токены.

Идентификатор библиотеки и версия

Идентификатор выглядит как путь: /vercel/next.js, /supabase/supabase, /mongodb/docs. Если знаете его заранее, можно назвать прямо в запросе и сэкономить шаг поиска - README показывает это так:

Версия добавляется третьим сегментом: /vercel/next.js/v14.3.0-canary.87. Отдельно указывать её обычно не нужно - достаточно упомянуть версию в самом вопросе, и подходящий идентификатор подберётся на шаге поиска:

Скил, который ставится вместе с MCP, прямо велит агенту предпочитать версионные идентификаторы, когда пользователь назвал версию. Это тот случай, когда одно слово в вопросе меняет качество ответа сильнее, чем любые настройки.

Один вопрос - один концепт

Самое полезное правило во всей документации проекта касается не установки, а формулировки запроса.

В описании query-docs прямо сказано, каким должен быть аргумент query: конкретным, с деталями и про одну тему. Там же приведены примеры хорошего и плохого:

Причина объяснена честно: широкий запрос размывает ранжирование и возвращает поверхностный результат по каждой из тем сразу. Если вопрос охватывает несколько разных концепций, скил велит агенту разрешить идентификатор один раз и сделать по отдельному вызову query-docs на каждую тему. Исключение одно - когда вопрос как раз про то, как эти вещи взаимодействуют между собой.

Практический вывод для человека, а не для агента: формулируйте задачу так, чтобы в ней была одна тема. "Настрой middleware и подключи авторизацию и поправь кэширование" - три разных вопроса в одном предложении, и документация по каждому из них придёт неполная.

Командная строка умеет больше, чем документацию

Если поставить скил context7-cli, выяснится, что ctx7 занимается тремя вещами: документацией, управлением скилами и настройкой MCP.

Документация - две команды, в строгом порядке:

Скилы - отдельный набор, который к самой документации отношения не имеет:

Вход и настройка:

Большинство команд работают без входа. Исключения перечислены в скиле: skills generate требует входа всегда, а ctx7 setup - если не передан --api-key или --oauth. Вход к тому же поднимает лимиты на запросы документации. Полностью обойти интерактивный вход можно переменной окружения:

Отдельного упоминания заслуживает раздел "Common Mistakes" в том же скиле - четыре ошибки, на которых спотыкаются в первый день:

• идентификатор библиотеки требует ведущего слэша: /facebook/react, а не facebook/react;
• сначала всегда ctx7 library - вызов ctx7 docs react "hooks" без валидного идентификатора упадёт;
• репозиторий для скилов задаётся как /owner/repo, например ctx7 skills install /anthropics/skills;
• skills generate без входа не работает.

Правило вместо скила

Если скил не ставился, агента можно подтолкнуть обычным правилом. README предлагает готовую формулировку, которую кладут в CLAUDE.md, в правила Cursor или в эквивалент вашего инструмента:

В репозитории есть и более подробный вариант - файл rules/context7-mcp.md. Он расписывает те же четыре шага, что и скил: сначала resolve-library-id, потом выбор лучшего совпадения по имени, релевантности описания, числу примеров, репутации источника и оценке качества, потом query-docs по одной теме, и только потом ответ.

Там же есть практическая мелочь, которая экономит время: если результаты выглядят не тем, чем надо, стоит попробовать другое написание названия - "next.js", а не "nextjs" - или переформулировать вопрос.

Что уходит на сервер

Вопрос закономерный, раз документация приходит извне.

Первое, что стоит знать: на сервер уходит не ваш исходный вопрос. Запрос формулирует модель на шаге вызова инструмента. В блоге Upstash это сказано прямо: "The query sent to Context7 is generated by the LLM, not your original prompt. Your actual question never leaves your machine - we only receive the LLM's reformulated query for documentation lookup."

Второе - предупреждение, встроенное прямо в описание инструмента query-docs: не включать в запрос ничего чувствительного, а именно ключи API, пароли, учётные данные, персональные данные и проприетарный код. Формулировка в исходнике адресована модели, но относится и к вам: если вы диктуете агенту запрос дословно, туда попадёт то, что вы продиктовали.

Третье касается качества, а не приватности. Первый пункт дисклеймера в README не оставляет двусмысленности: документация в Context7 добавляется сообществом, и проект не гарантирует её точность, полноту и безопасность. Проекты в индексе ведут их владельцы, а не Context7. Там же есть фраза, которую стоит прочитать целиком: "By using Context7, you acknowledge that you do so at your own discretion and risk."

Практический вывод простой. Свежая документация из индекса лучше, чем воспоминания модели двухлетней давности, но она не становится от этого первоисточником. Для критичных мест - миграций, безопасности, платежей - страницу проекта стоит открыть глазами.

Локальный запуск и проверка

Если нужно понять, что именно возвращает сервер, его запускают из исходников.

Тот же сервер по HTTP на своём порту:

И через stdio с ключом:

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

Когда что-то не работает

Руководство по неполадкам начинается с короткого чек-листа, и он покрывает большую часть случаев: проверить, что стоит Node.js 20 или новее; обновиться до последней версии пакета; проверить связь запросом curl https://mcp.context7.com/ping; добавить ключ, если упираетесь в лимиты; включить подробные логи через DEBUG=* перед тем, как писать в поддержку.

Совет, который стоит первым в разделе подсказок, звучит обезоруживающе: проблемы с Node.js обходятся полностью, если подключаться к удалённому серверу вместо локального запуска. Большинство клиентов умеют работать с https://mcp.context7.com/mcp напрямую, и тогда локальный Node.js не нужен вовсе.

Из частных случаев в документации разобраны три, которые встречаются чаще прочих. При ERR_MODULE_NOT_FOUND предлагают заменить npx на bunx или deno. Отдельные разделы посвящены проблемам разрешения ESM и сертификатам TLS. Есть и настройка прокси: сервер читает переменные https_proxy и HTTPS_PROXY, а при желании прокси задаётся прямо в настройках MCP-клиента.

Цифры, которые публикует проект

У Context7 есть измерения, и обращаться с ними надо аккуратно: это замеры вендора на собственных наборах вопросов, а не независимый аудит. Публикаций несколько, и базы сравнения у них разные.

В январе 2026 года вышла публикация про переход на новую архитектуру: заявлено снижение контекста примерно с 9.7 тысяч до 3.3 тысяч токенов, сокращение задержки с 24 до 15 секунд и уменьшение числа вызовов инструментов с 3.95 до 2.96. Методика описана: больше восьмидесяти вопросов по программированию, старую и новую архитектуру прогоняли на одинаковых наборах, качество оценивала отдельная модель по десятибалльной шкале.

В мае 2026 года опубликовано сравнение с веб-поиском Claude Code - там другие метрики и другая база: средние показатели снижения общего числа токенов и стоимости.

В июле 2026 года вышел третий замер, для среды без интернета: пятьдесят вопросов в пяти категориях, одна и та же модель в двух режимах - только собственные знания против локально обслуживаемой документации Context7. Оттуда самая наглядная пара чисел: выдуманных API десять против нуля.

Складывать эти цифры в один вывод нельзя - у них разные базы сравнения. Полезнее другое: методика в каждой публикации описана, и это уже отличает их от маркетинговых процентов без объяснения, откуда они взялись.

Чего Context7 не делает

Он не заменяет чтение документации человеком - он экономит переключение между окнами, пока вы пишете код с агентом.

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

Он не гарантирует, что документация в индексе полна и точна: её приносит сообщество.

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

Ошибки первого знакомства

Ставить MCP там, где хватило бы скила. Если агент и так запускает команды в терминале, режим CLI + Skills проще: меньше движущихся частей и нет ещё одного сервера, который надо поднимать.

Задавать один широкий вопрос вместо трёх узких. Ранжирование размывается, и по каждой теме приходит поверхностный результат. Проект прямо просит разбивать такие вопросы на отдельные вызовы.

Забывать слэш в идентификаторе. /facebook/react работает, facebook/react - нет. Ошибка стоит одного неудачного вызова и минуты недоумения.

Вызывать docs без library. Порядок не рекомендация, а требование: без валидного идентификатора вторая команда упадёт.

Держать ключ и во флаге, и в переменной окружения. Флаг побеждает всегда, и переменная тихо игнорируется - это самая обидная из здешних неочевидностей.

Путать требования к Node.js. Восемнадцатая версия годится командной строке, но не MCP-серверу: ему нужен минимум 20.18.1.

Считать индекс первоисточником. Документация добавляется сообществом, гарантий по точности проект не даёт и говорит об этом прямым текстом.

Если свести всё к одной фразе: Context7 полезен ровно там, где вопрос про библиотеку, и ровно настолько, насколько точно этот вопрос сформулирован.

Источники

Статья сверена с репозиторием upstash/context7 (ветка master), официальной документацией и публикациями блога Upstash 25 августа 2026 года: README, packages/mcp/package.json, packages/cli/package.json, исходник MCP-сервера packages/mcp/src/index.ts, руководство разработчика, руководство по неполадкам, скилы context7-mcp и context7-cli, правило rules/context7-mcp.md. Проект развивается быстро, версии командной строки и MCP-сервера меняются независимо, поэтому перед настройкой стоит заново заглянуть в README установленной версии.

• GitHub: upstash/context7
• Сайт Context7
• Исходник MCP-сервера
• Скил context7-mcp
• Скил context7-cli
• Правило для агента
• Руководство разработчика
• Руководство по неполадкам
• Настройка для 30+ клиентов
• Справочник командной строки
• Как добавить свою библиотеку
• Справочник REST API
• Блог: новая архитектура и её замеры
• Блог: сравнение с веб-поиском
• Блог: замер в среде без интернета