Перейти к основному содержимому

Авторизация удалённого MCP

Установите клиентский плагин CodeGraph, подключите MCP и пройдите авторизацию в Codex, VS Code, Cursor, GitHub Copilot или OpenCode.

Интеграции

Выберите способ подключения к вашей установке CodeGraph:

  • Для опубликованного сервиса используйте пакет Agent Plugins и вход через браузер. Порядок действий приведён в разделе «Перед входом» и инструкции для вашего клиента.
  • Для сервера в сети организации получите адреса и пакет у администратора. Следуйте разделу «Подготовка к подключению внутреннего сервера»; в нём отдельно описаны нативный плагин Codex и прямое HTTPS-подключение.
  • Для CI используйте API-ключ или сервисную учётную запись из раздела «Машинный доступ».

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

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

Подготовка к подключению внутреннего сервера

Если CodeGraph развёрнут в сети вашей организации, сначала войдите и получите доступ к проекту. Попросите администратора предоставить HTTPS-адрес MCP, способ авторизации, адреса веб-интерфейса и API, а также ссылку или разрешённый канал для получения пакета нужной версии.

С устройства, уже подключённого к сети организации, используйте HTTPS-адрес напрямую: локальный SSH-туннель не нужен. Архив пакета можно получить отдельно разрешённым способом.

Примеры ниже показывают scp как необязательный способ передачи архива: эта команда не создаёт MCP-туннель и не передаёт трафик MCP. Команды выполняются на рабочей станции. Установите Codex через разрешённый канал; проверьте codex --version.

Примеры распаковки ниже устанавливают нативный плагин Codex с транспортом stdio. Для прямого HTTPS-подключения следуйте разделу HTTPS-доступ через обратный прокси; установка нативного плагина для этого подключения не требуется.

Windows PowerShell (ssh и scp нужны только для необязательной передачи архива):

Если вы получили архив другим разрешённым способом, пропустите необязательную команду scp.

Set-Location "$env:USERPROFILE\Downloads"
scp -r -o 'User=<SSH_LOGIN>' '<SSH_HOST>:<DISTRIBUTION_PATH>' .
Set-Location '.\<DISTRIBUTION_DIRECTORY>'
Get-Content .\SHA256SUMS | ForEach-Object {
  $expected,$name=$_ -split '\s+',2
  if ((Get-FileHash -LiteralPath $name.Trim() -Algorithm SHA256).Hash -ne $expected) { throw "SHA-256 mismatch: $name" }
}
Expand-Archive '.\<CODEX_PLUGIN_ARCHIVE.zip>' -DestinationPath .\codex-plugin
$env:CODEX_HOME="$env:USERPROFILE\.codex-codegraph\my-project"
New-Item -ItemType Directory -Force $env:CODEX_HOME | Out-Null
codex login
codex plugin marketplace add .\codex-plugin --json
codex plugin add 'codegraph@<MARKETPLACE_NAME>' --json
codex mcp get codegraph --json

macOS или Ubuntu, Bash (unzip и Python 3 обязательны; ssh и scp нужны только для передачи архива):

cd "$HOME/Downloads"
scp -r -o 'User=<SSH_LOGIN>' '<SSH_HOST>:<DISTRIBUTION_PATH>' .
cd '<DISTRIBUTION_DIRECTORY>'
if [ "$(uname -s)" = Darwin ]; then
  shasum -a 256 -c SHA256SUMS || exit 1
else
  sha256sum -c SHA256SUMS || exit 1
fi
mkdir -p codex-plugin
unzip '<CODEX_PLUGIN_ARCHIVE.zip>' -d codex-plugin
export CODEX_HOME="$HOME/.codex-codegraph/my-project"
mkdir -p "$CODEX_HOME"
codex login
codex plugin marketplace add ./codex-plugin --json
codex plugin add 'codegraph@<MARKETPLACE_NAME>' --json
codex mcp get codegraph --json

Замените параметры в угловых скобках значениями своей поставки. Имя каталога плагинов (<MARKETPLACE_NAME>) указано в манифесте архива. При ошибке проверки SHA-256 остановитесь и запросите архив повторно. Распаковывайте его только после успешной проверки. Сохраняйте один CODEX_HOME для установки и рабочих сессий. codex login авторизует Codex, но для CodeGraph требуется отдельная авторизация.

HTTPS-доступ через обратный прокси

Администратор настраивает внутреннее DNS-имя и сертификат TLS для обратного прокси. Сертификат должен быть доверенным для рабочих станций и покрывать все опубликованные имена. Прокси принимает HTTPS на TCP 443. Разрешите подключения к этому порту из сети организации и через VPN; при работе извне сначала подключитесь к VPN организации. Внутри сети VPN не требуется. Для OAuth направьте следующие пути URL на внутренние сервисы:

  • /agent-plugin/mcp и /.well-known/oauth-protected-resource/agent-plugin/mcp направьте на MCP-сервис, порт 27495.
  • /.well-known/oauth-authorization-server/api/v1/auth/mcp и /api/v1/auth/mcp/ направьте на API-сервис, порт 8000.

Установите CODEGRAPH_MCP_REMOTE_AUTH_MODE=oauth и задайте публичные HTTPS-адреса, совпадающие с адресами в метаданных OAuth:

CODEGRAPH_AGENT_PLUGIN_MCP_PUBLIC_URL=https://<PUBLIC_HOST>/agent-plugin/mcp
CODEGRAPH_MCP_OAUTH_ISSUER=https://<PUBLIC_HOST>/api/v1/auth/mcp

Укажите в обоих URL одно внутреннее DNS-имя и один внешний порт, чтобы совпадали схема HTTPS, имя хоста и порт. Передавайте заголовки Host и X-Forwarded-Proto: https, сохраняйте пути и методы запросов, а также заголовок Authorization. Потоковые ответы MCP передавайте без буферизации.

Настройте межсетевой экран так, чтобы порты 27495 и 8000 принимали соединения только от обратного прокси. Если он работает на отдельном узле, разрешите подключения к этим портам только с этого узла. Рабочие станции во внутренней сети подключаются к HTTPS-адресу прокси напрямую.

В отдельном CODEX_HOME добавьте MCP-сервер и пройдите OAuth-вход. Замените <PUBLIC_HOST> и, если используется нестандартный внешний порт, укажите его в обоих URL:

codex mcp add codegraph-internal --url https://<PUBLIC_HOST>/agent-plugin/mcp --oauth-resource https://<PUBLIC_HOST>/agent-plugin/mcp
codex mcp login codegraph-internal --oauth-client-registration dcr
codex mcp get codegraph-internal --json

Проверьте, что codex mcp get показывает тот же HTTPS-адрес. Для поставки с личным Bearer-токеном отправьте POST <API_URL>/api/v1/auth/token с телом {"username":"<личный-логин>","password":"<личный-пароль>"}. Схемы REST-запросов доступны по <API_URL>/api/docs и <API_URL>/api/openapi.json. Если пакет ожидает переменную CODEGRAPH_MCP_TOKEN, задайте в ней полученный access_token в том же терминале, из которого запускаете Codex. Не записывайте токен в проект или config.toml.

Windows PowerShell:

$api='<API_URL>/api/v1'
$credential=Get-Credential
$body=@{username=$credential.UserName;password=$credential.GetNetworkCredential().Password} | ConvertTo-Json
$env:CODEGRAPH_MCP_TOKEN=(Invoke-RestMethod -Method Post -Uri "$api/auth/token" -ContentType 'application/json' -Body $body).access_token

macOS или Ubuntu, Bash:

export CODEGRAPH_API_URL='<API_URL>'
export CODEGRAPH_MCP_TOKEN="$(python3 - <<'PY'
import getpass
import json
import os
import sys
import urllib.request

sys.stderr.write('CodeGraph login: ')
with open('/dev/tty', encoding='utf-8') as terminal:
    username = terminal.readline().rstrip('\n')
password = getpass.getpass('CodeGraph password: ')
body = json.dumps({'username': username, 'password': password}).encode()
request = urllib.request.Request(
    os.environ['CODEGRAPH_API_URL'] + '/api/v1/auth/token',
    data=body,
    headers={'Content-Type': 'application/json'},
    method='POST',
)
with urllib.request.urlopen(request, timeout=15) as response:
    print(json.load(response)['access_token'])
PY
)"

Откройте локальную копию репозитория своего проекта и запустите codex. Проверьте ответ MCP-сервера вызовом codegraph_runtime_stack_status_get с пустыми аргументами; вызов MCP выглядит так:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"codegraph_runtime_stack_status_get","arguments":{}}}

Затем вызовите codegraph_project_context_status и codegraph_project_context_sync_status с {} и проверьте доступ к выбранному проекту по результатам этих вызовов. При status: denied пройдите авторизацию и повторите проверку. Для другого Agent Plugins-клиента распакуйте <AGENT_PLUGIN_ARCHIVE.zip> и установите его как локальный плагин через интерфейс клиента. Клиент должен поддерживать Streamable HTTP MCP и передавать личный токен. Сохраните действующие правила в AGENTS.md своего проекта и укажите в нём его каталог документации; шаблон из поставки проверяйте перед копированием.

Перед входом

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

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

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

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

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

codex mcp login codegraph --oauth-client-registration dcr

Войдите в CodeGraph, укажите разрешённое уникальное имя проекта или UUID проекта, подтвердите два разрешения MCP и вернитесь в Codex.

Проверьте соединение командой codex mcp list или /mcp, затем вызовите через Codex один доступный только для чтения инструмент контекста проекта.

Чтобы удалить сохранённые OAuth-данные, выполните codex mcp logout codegraph. Для смены пользователя или восстановления после отзыва токена снова выполните команду входа. Не записывайте токен доступа в пакет или 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 VS Code сам откроет браузер. Войдите, укажите уникальное имя проекта или UUID проекта и подтвердите разрешения.

После возврата проверьте статус подключения и вызовите один доступный только для чтения инструмент CodeGraph в режиме Agent.

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

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

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

agent mcp login codegraph

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

GitHub Copilot CLI

Установите Agent Plugin из зарегистрированного marketplace или локального пакета вашей поставки либо добавьте удалённый сервер через интерфейс управления MCP. В интерактивном CLI проверьте /mcp list, затем выполните:

/mcp auth codegraph

Завершите авторизацию в браузере и проверьте один вызов чтения в разрешённом проекте. При статусе needs-auth повторите ту же команду. Режим без интерактивного входа client_credentials не входит в универсальный пакет для входа пользователя. Автоматизация должна применять отдельно администрируемый API-ключ или сервисную учётную запись CodeGraph и хранить секрет в системном хранилище учётных данных или менеджере секретов.

Подключение OpenCode

OpenCode не указан в реестре совместимых клиентов Agent Plugins. Настройте удалённый сервер напрямую в opencode.json:

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

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

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

Пользователи входят через OAuth. Для CI или оператора без интерактивного входа выберите способ выдачи учётных данных:

  • Вошедший пользователь создаёт личный API-ключ через POST /api/v1/me/api-keys; операции создания и отзыва описаны в справочнике API.
  • Администратор создаёт сервисную учётную запись и выдаёт её первые учётные данные через POST /api/v1/admin/identity/service-accounts; операции ротации и отзыва приведены в разделе управления учётными записями.

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

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

Проверьте, что клиент показывает активный сервер, вызов чтения возвращает ответ и выбран нужный проект. Вызовите codegraph_project_context_status и codegraph_project_context_sync_status с {} и проверьте состояние контекста проекта. Если ответ сообщает о недоступной серверной памяти или устаревшем индексе, передайте администратору название проекта и ответ инструмента.

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

  • 401 с resource_metadata: действующих данных нет; запустите нативное действие входа клиента.
  • 401 invalid_token: токен истёк, отозван или не совпал issuer, audience либо resource; удалите сохранённые данные и войдите снова.
  • 403: у пользователя нет нужного разрешения или членства в проекте; запросите доступ, не меняйте заголовок проекта вручную.
  • Адрес возврата браузера отклонён: удалите динамическую регистрацию и повторите вход. CodeGraph принимает HTTPS, точный адрес возврата HTTP на локальный компьютер с исключением для динамического порта по RFC 8252 и указанный выше точный адрес возврата 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.

Сообщить об ошибке в документации