# Core MCP Troubleshooting

Source checked: 2026-07-24

Start with the failure class, then use the smallest recovery path.

## MCP server does not appear

- Confirm the harness config file or settings entry was saved.
- Ask the user to restart or reload the app if the harness requires it.
- Re-fetch the current harness guide and compare config shape.

## Tools are missing

- Call `tools/list` if the harness exposes diagnostics.
- Confirm the endpoint is the complete Core Secure server address, not the website root. During onboarding, keep the `setup_attempt` query parameter.
- Confirm the user completed OAuth or the bearer key is present.
- For local harnesses, explain that `localhost` or `127.0.0.1` OAuth callback URLs are expected and are not the MCP server location.

## OAuth failed

- Fetch the protected resource metadata for `/mcp/continuity`.
- Confirm the authorization server is present.
- Confirm the client requested Core-advertised `scopes_supported`. Core's interactive OAuth contract includes `openid`, `profile`, `email`, `user:org:read`, and `offline_access`.
- For Claude web, remember Claude connects from Anthropic cloud infrastructure. The MCP server must be publicly reachable from Anthropic, not just from the user's device.
- For Claude web, if the UI shows `Authorization with the MCP server failed` with an `ofid_...` reference, treat that reference as a support/correlation id that may be Anthropic-side unless it appears in Core logs. Do not assume it is a Core log id.
- For Claude web, confirm the auth server supports Dynamic Client Registration or that the user entered configured OAuth Client ID/Secret in Claude Advanced settings. Also confirm Claude's redirect URI is accepted by the OAuth provider.
- For ChatGPT web, confirm the auth server supports one ChatGPT client registration path: Client ID Metadata Documents, Dynamic Client Registration, or predefined OAuth client credentials. Also confirm the ChatGPT callback URL is allowlisted.
- For Cursor, an unauthenticated Core server may expose only `mcp_auth`. Use that tool or Cursor Settings -> Tools & MCPs -> Connect to finish OAuth.
- If a Codex build says OAuth requires an experimental flag or fails parsing metadata, update Codex instead of enabling experimental OAuth flags.
- For OpenCode, do not run `opencode mcp auth <name>` just because it was printed as an available command. Run it only when OpenCode reports missing/stale auth.
- Ask the user to retry browser consent once after the metadata, client scopes, or callback configuration has been corrected.
- Fall back to a scoped connector key only if the harness cannot complete OAuth.

## Claude Code failed

- If setup registered Core but `/mcp` does not show Core, do not assume auth failed. Claude Code may not load newly added MCP servers into the current session.
- Ask the user to fully quit/relaunch Claude Code or start a fresh Claude Code session, then run `/mcp` again.
- Only ask the user to authenticate after Core appears in `/mcp`.
- If `/mcp` shows Core but says it needs authentication, select Core and approve browser login. If browser auth completes but Core remains unauthenticated, restart Claude Code once and check `/mcp` again.

## Claude web failed

- Confirm the user pasted the complete Secure server address from Core into Remote MCP server URL. Outside onboarding, use `https://core.gradien.ai/mcp/continuity`.
- Confirm the user chose Add custom connector. For Team or Enterprise plans, an Owner may need to add it in Organization settings before members can connect.
- Fetch `/.well-known/oauth-protected-resource/mcp/continuity`; it must be valid JSON and include `authorization_servers`.
- Fetch the authorization server metadata; it must include authorization and token endpoints, PKCE S256 support, and Dynamic Client Registration or a configured Claude OAuth client.
- If Claude gives an `ofid_...` reference, search Core/Fly logs for it, but if no match exists, treat it as Anthropic-side and continue with metadata, DCR/client credentials, redirect URI, scope, and audience checks.
- If no Core logs show `/mcp` discovery or auth challenge traffic after this PR is deployed, suspect network reachability from Anthropic cloud or a failure before Claude reached Core.

## Cursor failed

- Confirm Cursor Settings -> Tools & MCPs contains Core with the complete Secure server address. For manual global configuration, confirm `~/.cursor/mcp.json` contains `"core": { "url": "https://core.gradien.ai/mcp/continuity" }` under `mcpServers`, while preserving any other servers.
- Reload Cursor with Cmd+Shift+P -> Developer: Reload Window, or open a new Cursor window.
- If Core appears as `user-core`, unauthenticated, or with only `mcp_auth`, finish OAuth by running `mcp_auth` from chat or clicking Connect in Cursor Settings -> Tools & MCPs.
- If Cursor stays on `Waiting for callback...` or `Exchanging token...` after the user clicks Allow and opens Cursor, do not keep clicking Connect or Allow. Fully quit/relaunch Cursor once, then check Cursor MCP Logs.
- If Fly/Core logs show repeated unauthenticated `/mcp` requests with a `Cursor/<version>` user agent but no authenticated requests, Core is reachable and Cursor did not complete/store OAuth.
- Check MCP Logs from the Output panel (Cmd+Shift+U) -> MCP Logs for connection, OAuth, or JSON parse errors.
- Fetch Core protected-resource metadata and the auth-server metadata. Cursor supports remote Streamable HTTP servers, OAuth, static OAuth client credentials, and a fixed redirect URI `cursor://anysphere.cursor-mcp/oauth/callback`; compare those docs before changing config shape.
- If native OAuth keeps hanging after one clean relaunch, fall back only with explicit user approval: create a scoped Core connector key, then configure Cursor remote headers as `Authorization: Bearer <key>` or `Bearer ${env:CORE_CONNECTOR_KEY}` if that Cursor version resolves header interpolation.
- Do not paste long-lived Core connector keys into `mcp.json` unless OAuth is impossible, the user explicitly approves that fallback, and you explain the local plaintext storage/rotation tradeoff.

## OpenCode failed

- Run `opencode mcp list` to inspect auth status before starting auth.
- If OpenCode asks `core already has valid credentials. Re-authenticate?`, choose No unless verification still shows auth is broken.
- If Core tools are missing after choosing No, run `opencode mcp debug core` and check whether the failure is discovery, OAuth, token exchange, or tool listing.
- If `opencode mcp debug core` says authenticated but the server returns `401 after successful authentication`, suspect a stale or under-scoped token. Check the token scope only through safe metadata/debug output; do not print, paste, curl with, or store the raw access token.
- If OpenCode says credentials are valid but the server still shows `needs_auth`, run `opencode mcp logout core`, then `opencode mcp auth core` once.
- If auth loops continue, fetch Core protected-resource metadata and confirm `scopes_supported` includes `user:org:read`, then check OpenCode's stored credentials file only at a metadata level; do not print tokens.

## Codex failed

- Verify `codex mcp list` and the `[mcp_servers.core]` entry in `~/.codex/config.toml`.
- Confirm the configured URL is the complete Secure server address, or `https://core.gradien.ai/mcp/continuity` outside onboarding. Local `~/.codex` paths and localhost OAuth callbacks are normal Codex client state, not the Core server.
- Do not add a custom OAuth resource. If an OAuth error says `resource` appears more than once, remove that override and let Codex discover Core's protected-resource metadata.
- Do not retry with `--scopes profile,email`; let Codex use Core metadata. If a stale token was minted before metadata changed, run `codex mcp logout core`, then `codex mcp login core`.
- If Codex says remote OAuth requires an experimental setting, or OAuth metadata parsing fails on an old build, check `codex --version` and update Codex. Do not persist experimental OAuth flags as part of setup.
- If `codex mcp login core` reports success but a new Codex runtime still gets AuthRequired during tool discovery, ask the user to update/restart Codex and retry once. Avoid repeated nested `codex exec` probes.
- Prefer the Core local bridge path only after native OAuth fails with a clean config, clean login, fresh Codex session, and current Codex version.
- Verify the bridge can call Core `tools/list` when using the bridge fallback.

## ChatGPT web failed

- Confirm Developer mode is enabled at the bottom of Settings -> Plugins.
- In Settings -> Plugins, choose Create app (or Browse plugins -> `+` if your account shows that path), use Server URL, and paste the complete Secure server address from Core into MCP Server URL. Outside onboarding, use `https://core.gradien.ai/mcp/continuity`.
- Use OAuth for production Core. Do not use No Authentication against user memory except on a separate disposable smoke-test server.
- Fetch `/.well-known/oauth-protected-resource/mcp/continuity` and confirm `authorization_servers` is present.
- Fetch the authorization server metadata and confirm it has authorization and token endpoints, PKCE S256 support, and either Client ID Metadata Documents, Dynamic Client Registration, or a predefined OAuth client configured in ChatGPT.
- Confirm the ChatGPT redirect URL shown in app settings, usually `https://chatgpt.com/connector/oauth/{callback_id}`, is allowlisted by the OAuth provider.
- If ChatGPT redirects with `error=invalid_scope` and says the OAuth client cannot request `openid`, inspect the dynamically registered client. It must allow `openid`, `profile`, `email`, `user:org:read`, and `offline_access`. Repair the exact affected client or create one new plugin after the authorization server's DCR defaults are corrected.
- If ChatGPT shows only “There was a problem connecting Core. Try again later,” treat it as likely OAuth registration/redirect/provider metadata failure until proven otherwise.

## Wrong workspace

- Ask the user which Core workspace they intended to connect.
- Have them sign into the correct workspace in the browser.
- Do not reuse a connector key from another workspace.

If stuck, fetch the full context at https://core.gradien.ai/core/llms-full.txt and report the exact harness, command/config used, error text, and whether OAuth or bearer auth was attempted.