Remote MCP authentication

Use the separate plugins/codegraph-agent-plugin package for a remote CodeGraph deployment. 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 stores the resulting credentials in its own secure store. This is different from the native local Codex package under plugins/codegraph, which continues to use trusted stdio.

Install or import the portable package from plugins/codegraph-agent-plugin using the client’s Agent Plugin UI, marketplace, or local-plugin setting.
Confirm that the discovered server is named codegraph and its URL is https://api.codegraph.ru/agent-plugin/mcp.
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 form binds the token to the canonical project UUID; changing X-Project-ID cannot widen access. The standalone consent page uses the same visual tokens and form hierarchy as the CodeGraph frontend login page; verify the CodeGraph CG mark and the client name before entering credentials.
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 --oauth-client-registration dcr

Then run, or rerun after the initial flow:

codex mcp login codegraph

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:

cursor-agent mcp login codegraph

agent is an installed alias of cursor-agent, but the documented command is portable across Cursor CLI installations. Complete the browser flow, then check cursor-agent mcp list and cursor-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 directly from the released repository subdirectory (copilot plugin install OWNER/REPO:plugins/codegraph-agent-plugin), or 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, so do not claim that it loads this portable package. 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"
    }
  }
}

Then run opencode mcp auth codegraph (or select CodeGraph under /connect), 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, create a bounded CodeGraph API key or service account and configure it 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.

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.

Before login