# Core MCP Troubleshooting

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.
- Restart or reload the app if that harness discovers MCP servers only at startup.
- Reopen the current agent-specific guide and compare the saved config shape.

## Tools are missing

- Call `tools/list` if the harness exposes diagnostics.
- Confirm the endpoint is Core MCP, not the website root.
- 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.
- Confirm the authorization server is present.
- Confirm the client requested Core-advertised `scopes_supported`; for Core this includes OpenID sign-in identity plus workspace/org selection consent where the authorization server supports it.
- 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 -> Features -> Model Context Protocol -> Connect/Authenticate 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.
- Retry browser consent once after checking the metadata and app state.
- 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.
- Fully quit/relaunch Claude Code or start a fresh Claude Code session, then run `/mcp` again.
- Authenticate only 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 exact remote MCP server URL: `https://core.gradien.ai/mcp`.
- 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`; 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/mcp.json` contains `"core": { "url": "https://core.gradien.ai/mcp" }` 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/Authenticate in Cursor Settings -> Features -> Model Context Protocol.
- 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 get core`.
- Confirm the config URL is the Core MCP endpoint, for example `https://core.gradien.ai/mcp`; local `~/.codex` paths and `localhost` OAuth callbacks are normal Codex client state, not the Core server.
- Do not add `--oauth-resource` for Core. If you see an OAuth error saying `resource` appears more than once, remove that config and return to `codex mcp add core --url <baseUrl>/mcp`.
- 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, 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

- Use Server URL, not Tunnel, for hosted Core: `https://core.gradien.ai/mcp`.
- 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` 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 back with `error=invalid_scope` and says the OAuth client is not allowed to request `openid`, confirm Core protected-resource metadata advertises `openid` in `scopes_supported`, then delete/recreate the draft ChatGPT app or re-register OAuth so ChatGPT gets a new client allowed to request the updated scopes.
- 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

- Confirm which Core workspace should be connected.
- 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://gradien.ai/core/llms-full.txt and report the exact harness, command/config used, error text, and whether OAuth or bearer auth was attempted.