Skip to main content

Remote MCP authentication

Install a CodeGraph client plugin, connect MCP, and authorize Codex, VS Code, Cursor, GitHub Copilot, or OpenCode for your instance.

Integrations

Choose the connection for your CodeGraph instance:

  • For the hosted service, use the Agent Plugins package and browser login. Follow “Before login” and the instructions for your client.
  • For a server on your organization’s network, obtain the URLs and package from the administrator. Follow “Client for an internal server”, which describes the native Codex plugin and direct HTTPS connection separately.
  • For CI, use an API key or service account as described in “Machine access”.

Use the portable Agent Plugins package supplied by the operator for the hosted CodeGraph service. It targets Agent Plugins 1.0.0 and contains one fixed Streamable HTTP URL. It does not contain a token, API key, OAuth client secret, credential reference, stdio command, SSE endpoint, or fallback.

The package format deliberately has no OAuth fields. The client receives a 401 Bearer challenge, discovers CodeGraph authorization metadata, registers a public client, opens the browser, uses S256 PKCE, and manages the resulting credentials in its own credential store. This is different from the native Codex package, which is a separate artifact using trusted stdio.

Client for an internal server

If CodeGraph runs in your organization’s network, first sign in and get project access. Ask the administrator for the HTTPS MCP URL, sign-in method, UI and API URLs, and a link or approved channel for the matching package version. From a device already connected to the organization’s network, use the HTTPS URL directly; no local SSH tunnel is needed. The package can be transferred separately through an approved channel. The commands below show scp as an optional way to transfer the package; it does not create an MCP tunnel or carry MCP traffic. Run the commands on your workstation. Install Codex through an approved channel and check codex --version.

The archive commands below install the native Codex plugin using stdio. For a direct HTTPS connection, follow HTTPS access through a reverse proxy; that connection does not require the native plugin.

Windows PowerShell (ssh and scp are needed only for the optional package transfer):

If you obtained the archive through another approved channel, skip the optional scp command.

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 or Ubuntu, Bash (unzip and Python 3 are required; ssh and scp are only for package transfer):

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

Replace angle-bracket parameters with your distribution values; the marketplace name is in the package manifest. Stop if SHA-256 verification fails and obtain the archive again. Extract it only after successful verification. Use one CODEX_HOME for installation and working sessions. codex login authorizes Codex itself; CodeGraph requires a separate sign-in.

HTTPS access through a reverse proxy

The administrator configures an internal DNS name and TLS certificate for the reverse proxy. The certificate must be trusted by workstations and cover every published hostname. The proxy accepts client HTTPS on TCP 443. Allow connections to this listener from the organization network and over VPN; users outside the network must connect through the organization’s VPN first. VPN is not needed inside the network. For OAuth, route these URL paths to internal services:

  • Forward /agent-plugin/mcp and /.well-known/oauth-protected-resource/agent-plugin/mcp to the MCP service on port 27495.
  • Forward /.well-known/oauth-authorization-server/api/v1/auth/mcp and /api/v1/auth/mcp/ to the API service on port 8000.

Set CODEGRAPH_MCP_REMOTE_AUTH_MODE=oauth and configure the public HTTPS URLs to match the URLs advertised by OAuth discovery:

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

Use the same internal DNS hostname for both URLs so they share one HTTPS origin. Forward Host and X-Forwarded-Proto: https, preserve request paths and methods, and pass the Authorization header. Stream MCP responses without buffering. Configure the firewall so only the reverse proxy can connect to ports 27495 and 8000. If the proxy runs on another host, allow connections to these ports only from that host. Workstations on the organization’s internal network connect directly to the proxy’s HTTPS address.

In a dedicated CODEX_HOME, add the MCP server and sign in with OAuth. Replace <PUBLIC_HOST> and, if a non-standard external port is used, include it in both URLs:

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

Confirm that codex mcp get shows the same HTTPS URL. For a distribution using a personal Bearer token, call POST <API_URL>/api/v1/auth/token with {"username":"<personal-login>","password":"<personal-password>"}. The REST schemas are at <API_URL>/api/docs and <API_URL>/api/openapi.json. If the package expects CODEGRAPH_MCP_TOKEN, set it to the returned access_token in the same terminal that starts Codex. Do not write the token to your project or 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 or 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
)"

Open your local project checkout and start codex. Check that the MCP server responds by calling codegraph_runtime_stack_status_get with empty arguments. The MCP request is:

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

Then call codegraph_project_context_status and codegraph_project_context_sync_status with {} and verify access to the selected project from their results. For status: denied, authenticate and repeat the check. For another Agent Plugins client, extract <AGENT_PLUGIN_ARCHIVE.zip> and install it as a local plugin through that client’s UI. The client must support Streamable HTTP MCP and send the personal token. Keep the existing rules in your project’s AGENTS.md and point it to your repository’s documentation directory; review the packaged template before copying it.

Before login

  1. Install or import the supplied portable package using the client’s Agent Plugin UI, marketplace, or local-plugin setting.
  2. Confirm that the discovered server is named codegraph and its URL is https://api.codegraph.ru/agent-plugin/mcp.
  3. Know the unique project name you are allowed to use. Enter that human-readable name in the browser consent form. A project UUID is also accepted and is required when names are ambiguous. The token grants access to the selected project; changing X-Project-ID does not change that access. Before entering credentials, check the CodeGraph CG mark and MCP client name on the login page.
  4. Review the requested scopes: mcp:tools and mcp:project.

Codex CLI and IDE extension

If the portable plugin is not installed from a marketplace, register the same secret-free remote entry directly. Use lowercase dcr; it is the CLI enum value:

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

Then run, or rerun after the initial flow:

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

Complete the CodeGraph login, enter the authorized unique project name or project UUID, approve the two MCP scopes, and return to Codex. Verify the connection with codex mcp list or /mcp, then ask Codex to call a read-only CodeGraph project-context tool. To clear the stored OAuth credential, run codex mcp logout codegraph; run the login command again to change account or recover after revocation. Do not put an access token in the plugin package or config.toml.

In the Codex IDE extension, open MCP servers, select codegraph, and choose Authenticate. The CLI and IDE extension share the same Codex MCP configuration.

VS Code with GitHub Copilot

Enable Agent Plugins (chat.plugins.enabled), install the package through the Agent Plugins view, Chat: Install Plugin From Source, or a trusted chat.pluginLocations entry, then run MCP: List Servers from the Command Palette and start codegraph. VS Code opens the browser automatically when the server returns the OAuth challenge. Sign in, enter the unique project name or project UUID, and approve the scopes. After redirect, confirm that the server is connected and invoke one read-only CodeGraph tool from Agent mode.

Use Accounts > Manage Trusted MCP Servers to review trust. Use Authentication: Remove Dynamic Authentication Providers to remove a DCR registration, then reconnect to authenticate again. CodeGraph validates the exact registered callback, with only the RFC 8252 loopback-port exception; do not preconfigure or copy callback URLs between machines.

Cursor editor and CLI

After installing the package or configuring the same remote server in Cursor, start authentication from the MCP server panel. In Cursor CLI, run:

agent mcp login codegraph

Complete the browser flow, then check agent mcp list and agent mcp list-tools codegraph. Disable and re-enable the server to test reconnect. If the token was revoked or expired, rerun the login command; do not copy a token into .cursor/mcp.json. CodeGraph accepts Cursor’s exact RFC 8252 private-use registration callback cursor://anysphere.cursor-mcp/oauth/callback; arbitrary custom schemes, hosts and paths are rejected.

GitHub Copilot CLI

Install the Agent Plugin from a registered marketplace or your operator’s local package. You can also add the remote server through Copilot’s MCP management UI. In the interactive CLI, inspect it with /mcp list, then run:

/mcp auth codegraph

Complete browser authorization and verify one read-only project-scoped call. If status becomes needs-auth, run the same command again. Headless client_credentials is not part of the portable human-login package; automation must use the separately administered CodeGraph API-key or service- account contract and an operating-system keychain or secret manager.

OpenCode adapter scope

OpenCode is not listed in the Agent Plugins compatible-client registry. Configure the same remote MCP URL in opencode.json instead:

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

Run opencode mcp auth codegraph in your terminal, check opencode mcp list, and remove credentials with opencode mcp logout codegraph. OpenCode owns its OAuth credential store; the repository and portable package must remain secret-free.

Machine access

Interactive users should use OAuth. For CI or a headless operator, choose how to obtain credentials:

  • A signed-in user creates a personal API key through POST /api/v1/me/api-keys; see the API reference for creation and revocation operations.
  • An administrator creates a service account and issues its initial credential through POST /api/v1/admin/identity/service-accounts; see identity administration for rotation and revocation operations.

Configure the resulting credentials only in the client’s private MCP settings. A machine request needs X-API-Key, X-Project-ID, and X-CodeGraph-Machine-Contract: 2026-03-v1. Keep all three values outside plugin.json and mcp.json.

Codex can map private environment variables with env_http_headers. VS Code can use a secure input in user-level MCP configuration. Cursor and Copilot CLI should use their private credential store, keychain, or secret-manager integration. Agent Plugins headers are visible package data and must not contain these values. CodeGraph does not repair an OAuth failure by trying a machine key.

Check that the client shows an active server, a read-only call returns a response, and the selected project is correct. Call codegraph_project_context_status and codegraph_project_context_sync_status with {} to check project-context status. If the response reports unavailable server memory or a stale index, send the project name and tool response to the administrator.

Failure and recovery

  • 401 with resource_metadata: no valid credential; use the client’s native login action.
  • 401 invalid_token: expired, revoked, wrong-issuer, wrong-audience, or wrong-resource token; remove the stored credential and authenticate again.
  • 403: the identity lacks a required scope or project membership; request access instead of editing a project header.
  • Browser redirect rejected: remove the dynamic registration and retry. CodeGraph accepts HTTPS, exact loopback HTTP redirects with the RFC 8252 ephemeral-port exception, and the exact Cursor callback named above; S256 PKCE is mandatory.
  • Server unavailable: stop. Remote mode never falls back to stdio, SSE, or unauthenticated MCP.

Authoritative references: Agent Plugins 1.0.0, compatible clients, Codex MCP, VS Code MCP authorization, Cursor MCP CLI, GitHub Copilot CLI commands, and OpenCode MCP.

Report a documentation issue