Авторизация удалённого MCP — Документация CodeGraph

Для удалённого CodeGraph используйте отдельный пакет plugins/codegraph-agent-plugin. Он соответствует Agent Plugins 1.0.0 и содержит один фиксированный адрес Streamable HTTP. В пакете нет токена, API-ключа, секрета OAuth-клиента, ссылки на хранилище учётных данных, команды stdio, SSE-адреса или запасного транспорта.

В универсальном формате намеренно нет OAuth-полей. Клиент получает Bearer challenge с кодом 401, находит метаданные авторизации CodeGraph, регистрирует публичного клиента, открывает браузер, применяет S256 PKCE и сам хранит полученные данные. Нативный локальный пакет Codex из plugins/codegraph остаётся отдельным артефактом и продолжает работать через доверенный stdio.

Перед входом

Установите или импортируйте plugins/codegraph-agent-plugin через интерфейс Agent Plugins, marketplace или настройку локального плагина в выбранном клиенте.
Проверьте имя сервера codegraph и адрес https://api.codegraph.ru/agent-plugin/mcp.
Подготовьте уникальное имя проекта CodeGraph, к которому у вас есть доступ. В форме согласия удобнее указать это имя. UUID проекта тоже поддерживается и обязателен, если имена неоднозначны. Токен будет привязан к каноническому UUID; подмена X-Project-ID не расширит права. Отдельная страница согласия использует те же визуальные токены и структуру формы, что и вход во frontend CodeGraph. Перед вводом данных проверьте знак CG и название MCP-клиента.
Проверьте запрашиваемые scope: mcp:tools и mcp:project.

Codex CLI и расширение IDE

Если универсальный плагин не установлен из marketplace, добавьте ту же запись remote MCP напрямую. Значение enum dcr указывается в нижнем регистре:

codex mcp add codegraph --url https://api.codegraph.ru/agent-plugin/mcp --oauth-resource https://api.codegraph.ru/agent-plugin/mcp --oauth-client-registration dcr

Затем выполните или повторите после первичного входа:

codex mcp login codegraph

Войдите в CodeGraph, укажите разрешённое уникальное имя проекта или UUID проекта, подтвердите два MCP scope и вернитесь в Codex. Проверьте соединение командой codex mcp list или /mcp, затем вызовите через Codex один read-only инструмент контекста проекта. Чтобы удалить сохранённые OAuth-данные, выполните codex mcp logout codegraph. Для смены пользователя или восстановления после отзыва токена снова запустите login. Не записывайте access token в пакет или config.toml.

В расширении Codex откройте MCP servers, выберите codegraph и нажмите Authenticate. CLI и расширение используют общую конфигурацию MCP Codex.

VS Code с GitHub Copilot

Включите Agent Plugins (chat.plugins.enabled), установите пакет через список Agent Plugins, Chat: Install Plugin From Source либо доверенную запись chat.pluginLocations, откройте палитру команд и выполните MCP: List Servers, затем запустите codegraph. После OAuth challenge VS Code сам откроет браузер. Войдите, укажите уникальное имя проекта или UUID проекта и подтвердите scope. После возврата проверьте статус подключения и вызовите один read-only инструмент CodeGraph в Agent mode.

Доверие проверяется через Accounts > Manage Trusted MCP Servers. Для удаления DCR-регистрации используйте Authentication: Remove Dynamic Authentication Providers, затем подключитесь снова. CodeGraph сверяет точный зарегистрированный callback; исключение сделано только для динамического loopback-порта по RFC 8252. Не переносите callback-адрес между компьютерами вручную.

Cursor: редактор и CLI

После установки пакета или добавления того же удалённого сервера запустите авторизацию в панели MCP Cursor. В Cursor CLI выполните:

cursor-agent mcp login codegraph

agent устанавливается как алиас cursor-agent, но документированная команда переносима между установками Cursor CLI. Завершите вход в браузере, затем проверьте cursor-agent mcp list и cursor-agent mcp list-tools codegraph. Для проверки переподключения отключите и снова включите сервер. После истечения или отзыва токена повторите login; не копируйте токен в .cursor/mcp.json. CodeGraph принимает точный private-use callback Cursor по RFC 8252: cursor://anysphere.cursor-mcp/oauth/callback. Произвольные схемы, хосты и пути отклоняются.

GitHub Copilot CLI

Установите Agent Plugin из зарегистрированного marketplace или из подкаталога опубликованного репозитория (copilot plugin install OWNER/REPO:plugins/codegraph-agent-plugin) либо добавьте удалённый сервер через интерфейс управления MCP. В интерактивном CLI проверьте /mcp list, затем выполните:

/mcp auth codegraph

Завершите авторизацию в браузере и проверьте один read-only вызов в разрешённом проекте. При статусе needs-auth повторите ту же команду. Headless-режим client_credentials не входит в универсальный пакет для входа пользователя. Автоматизация должна применять отдельно администрируемый API-ключ или service account CodeGraph и хранить секрет в системном keychain или secret manager.

OpenCode: отдельный адаптер, несовместимый с Agent Plugins

OpenCode не указан в реестре совместимых клиентов Agent Plugins. Поэтому он полагается на отдельный плагин. Удалённый MCP должен быть указан в конфигурационном файлев opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "remote",
      "url": "https://api.codegraph.ru/agent-plugin/mcp"
    }
  }
}

Затем выполните opencode mcp auth codegraph или выберите CodeGraph через /connect, проверьте opencode mcp list, а для удаления данных используйте opencode mcp logout codegraph. Хранилищем OAuth управляет OpenCode; репозиторий и универсальный пакет остаются без секретов.

Машинный доступ

Пользователи входят через OAuth. Для CI или headless-оператора создайте ограниченный API-ключ либо service account CodeGraph и настройте его только в закрытой конфигурации MCP выбранного клиента. Машинному запросу нужны X-API-Key, X-Project-ID и X-CodeGraph-Machine-Contract: 2026-03-v1. Все три значения хранятся вне plugin.json и mcp.json.

Codex умеет брать закрытые значения из переменных среды через env_http_headers. В VS Code используйте secure input в пользовательской конфигурации MCP. Для Cursor и Copilot CLI подходят закрытое хранилище клиента, системный keychain или secret manager. Поле headers в Agent Plugins видно как обычные данные пакета, поэтому секретам там не место. После ошибки OAuth CodeGraph не пытается автоматически применить машинный ключ.

Ошибки и восстановление

401 с resource_metadata: действующих данных нет; запустите нативное действие входа клиента.
401 invalid_token: токен истёк, отозван или не совпал issuer, audience либо resource; удалите сохранённые данные и войдите снова.
403: у пользователя нет нужного scope или членства в проекте; запросите доступ, не меняйте заголовок проекта вручную.
Браузерный redirect отклонён: удалите динамическую регистрацию и повторите вход. CodeGraph принимает HTTPS, точный loopback HTTP redirect с исключением для динамического порта по RFC 8252 и указанный выше точный callback Cursor; S256 PKCE обязателен.
Сервер недоступен: остановитесь. Удалённый режим не переключается на stdio, SSE или MCP без авторизации.

Авторитетные источники: Agent Plugins 1.0.0, совместимые клиенты, Codex MCP, OAuth MCP в VS Code, Cursor MCP CLI, команды GitHub Copilot CLI и OpenCode MCP.