Coreby Gradien

Troubleshooting

Core MCP Troubleshooting

Back to setup docsRaw source

Paste this into your agent

Start with this visible request when you want the agent to help. It keeps the action coming from you, while the linked setup reference stays plain and non-recursive.

Use this in the app you are connecting, then approve only the browser login, app setting, or restart steps that the app requires.

Please help me set up Core for this agent. Core is a home base for AI agents: it keeps memory, files, decisions, tasks, and work context synced across tools, harnesses, and models.

Use this official setup reference:
https://gradien.ai/core/docs/reference

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.