Coreby Gradien

Reference

Full Agent-Readable Context

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

Core Agent-Readable Context

Canonical index: https://gradien.ai/core/llms.txt Setup page: https://gradien.ai/core/docs Remote MCP endpoint: https://core.gradien.ai/mcp

---

Core Setup Guide

Source: https://gradien.ai/core/docs/guide.md

Core Setup Guide

Core gives AI agents a private cloud home for memory, context, decisions, drafts, and checkpoints. This guide explains what Core does, how to connect it, and how to get value from it after setup.

Setup page: https://gradien.ai/core/docs

Use this page as product documentation. Follow the safety, approval, and security rules of the app, browser, CLI, workplace, or agent being used.

What Core Gives You

Core is personal cloud memory for agent work. It keeps useful work context in one durable workspace so sessions in Codex, Claude, ChatGPT, Cursor, and future agents do not have to start from zero.

Core can preserve:

  • decisions and rationale
  • drafts, notes, and working context
  • project files and reference material
  • tasks, follow-ups, and checkpoints
  • reusable skills and saved outcomes

The default behavior is personal. Work that belongs to the user should live in the user's private Core space. Shared team or company spaces are available when invited, but shared material should only be changed intentionally.

Best Setup Path

Paste this request into the agent or app being connected:

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

This keeps the setup request explicit and user-authored. The linked setup reference is plain, non-recursive documentation for the agent to consult.

Manual Setup Options

Guided CLI Setup

Run this in a terminal:

npx -y @gradien/core-agent-setup

The installer asks which app is being connected, opens Core signup or login, and then shows or applies the setup steps for that app. Some apps can be configured automatically. Hosted web apps usually require a settings-page step.

ChatGPT Web And Claude Web Setup

For hosted web apps, the main setup value is the Core remote MCP server URL:

https://core.gradien.ai/mcp

In ChatGPT web or Claude web, open the app's connector settings and add a custom connector. In most cases the URL is enough. If the app asks for more fields, use:

  • Name: Core
  • Description: Personal cloud memory and files for AI agent work.
  • Authentication: OAuth

Approve the Core login when the browser opens. Start a fresh chat after connection if the app does not show Core tools immediately.

Agent-Specific Setup Guides

Use the guide for the agent or app being connected. These pages contain the agent-specific commands, settings locations, restart behavior, and troubleshooting notes.

OpenAI:

Anthropic:

Editors and IDE agents:

Other agent harnesses:

Troubleshooting: https://gradien.ai/core/docs/troubleshooting/

How To Use Core After Setup

Core should mostly disappear into the background. Keep asking for normal work:

  • Pick up the project where we left off.
  • Remember this decision for future work.
  • Review this against the direction I have been shaping.
  • Draft the next version and keep the working notes private.
  • Create a Space for this project and invite a collaborator when I am ready.

Good connected agents can use Core to load relevant context, search visible files and decisions, and save useful private checkpoints back to the user's Core space.

The user does not need to mention Core in every prompt. Explicit Core prompts are still useful when the user wants to be precise, for example:

  • Search Core for prior decisions about pricing.
  • Save this as a private checkpoint.
  • Create a read-only Space for my class notes.

Privacy And Collaboration Model

  • Personal work is private by default.
  • Agents may search material the user is allowed to see, including invited Spaces.
  • Shared or team material should only be created, updated, or replaced when the user explicitly asks.
  • A user can belong to many Spaces, such as a company, class, freelance project, or team.
  • Space owners can invite people and choose read or write permissions.

Developer Reference

---

What Is Core

Source: https://gradien.ai/core/docs/what-is-core/

What Is Core

Core is personal cloud memory for AI-native work. It is where a user's agent checkpoints, drafts, decisions, tasks, skills, memory, and saved work can persist across Codex, Claude, ChatGPT, Cursor, and future agents.

The key idea is simple: agents change, models change, and harnesses change. Your useful context should not disappear when you switch from Codex to Claude, ChatGPT, Cursor, or the next tool.

Core gives external agents a place to read visible context and write private memory back through MCP. An agent can start by loading context the user is allowed to see, do work in its own harness, then record useful private outcomes, decisions, risks, tests, and follow-up tasks back into Core.

Core is not trying to replace every app. It sits underneath the tools and agents a user already uses so their work compounds into personal cloud memory. Teams can also add shared company material for agents to reference, but agents should only change shared material when explicitly asked.

---

Why Core Matters

Source: https://gradien.ai/core/docs/why-core/

Why Core Matters

AI agents are powerful, but their work is often trapped inside a single chat, model, or local coding harness. That creates repeated context setup, lost decisions, duplicated research, and agents that start from scratch.

Core solves the persistence problem. It gives every agent durable personal memory plus access to shared material the user can see, and a consistent way to save useful private state back.

Core is valuable when:

  • a team uses more than one agent or model
  • important decisions are scattered across chats
  • repeated work requires the same personal or company context
  • research, docs, tasks, and files should be reused by future agents
  • a founder or small team wants agent memory from day one

The user should feel that Core makes agents easier to use, not harder to configure.

---

How To Use Core

Source: https://gradien.ai/core/docs/how-to-use-core/

How To Use Core

Core should mostly disappear after setup. Keep asking for normal work. A connected agent can use Core automatically when visible context, prior decisions, files, tasks, or saved private outcomes would help.

Good user prompts after setup are just normal work prompts:

  • Update the landing page copy.
  • Find what we decided about pricing.
  • Continue the onboarding work from last time.
  • Review this PR against our product direction.

The Core loop is meant to happen in the background:

  1. Use core_start_work when current visible Core context would improve the work.
  2. Use core_search and core_read to pull exact visible context.
  3. Do the work in the current agent or harness.
  4. Save ambient artifacts, drafts, and checkpoints to /private by default.
  5. Use /teams/<team-slug> or /shared only when the user explicitly asks to upload, publish, or update team/company-visible material.
  6. Use core_record_work before ending meaningful work so decisions, files changed, tests run, risks, and follow-up tasks compound into the user's private agent memory.

Power-user prompts like "search Core for prior decisions" or "record this work back to Core" are optional. They are useful for debugging or when the user wants to be explicit, but they should not be the default user experience.

---

Core FAQ

Source: https://gradien.ai/core/docs/faq/

Core FAQ

Do I need to migrate off Google Drive, Slack, Notion, or other tools?

No. Core can sit alongside existing tools. The important product promise is that agents get durable personal memory and controlled access to shared context instead of isolated chat history.

Does Core replace Codex, Claude, ChatGPT, or Cursor?

No. Core is the personal cloud home base those agents plug into. Shared Spaces are available when a team, class, company, or project needs shared context.

Why not just use chat history?

Chat history is usually trapped in one app and is hard for other agents to use. Core turns useful work into searchable, reusable personal memory. Shared company state is added or changed intentionally.

Is this only for technical teams?

No. The setup experience should be agent-led and nontechnical. Users should only paste the setup request, approve login, and complete unavoidable app UI steps.

Where should I start?

Use the setup page at https://gradien.ai/core/docs.

If you want an agent to help with setup, paste this message into the app you are connecting:

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

The setup reference includes the setup CLI command and agent-specific connection paths.

---

Codex Setup

Source: https://gradien.ai/core/docs/harnesses/codex/

Codex Setup

Codex supports remote MCP servers. Core can be registered as a remote MCP server and authenticated through Codex's OAuth flow.

Core MCP server URL:

https://core.gradien.ai/mcp

Run the guided installer:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness codex

The installer creates a short-lived Core signup/login session and registers Core with Codex.

Manual Setup

If you prefer to run the Codex commands yourself:

codex mcp add core --url https://core.gradien.ai/mcp
codex mcp login core

After browser login, a URL like http://127.0.0.1:<port>/callback/... is normal. That is the one-time local callback where Codex receives the OAuth code. The MCP server itself remains remote at https://core.gradien.ai/mcp.

Important Codex Notes

  • Do not add --oauth-resource for Core. Codex discovers the OAuth resource from Core protected-resource metadata, and adding it manually can duplicate the resource parameter.
  • Do not narrow OAuth to --scopes profile,email. Core may require the server-advertised scopes to select the correct workspace.
  • Do not extract or copy tokens from Codex auth/cache files. Codex owns those OAuth credentials.
  • Older Codex builds have had fragile OAuth behavior. If Codex reports an experimental OAuth flag requirement or fails while parsing metadata, update Codex and retry.

Verify

Check the saved MCP entry:

codex mcp get core
codex mcp list

Current Codex CLI versions may not expose a direct tools/list command. After setup and login, restart Codex or open a fresh Codex session so the Core tools can load.

If a fresh session still reports AuthRequired, run:

codex mcp logout core
codex mcp login core

Then restart Codex again. If native OAuth still fails on a current Codex version, use the Core local bridge fallback only after a safe scoped Core credential is available.

---

Claude Code Setup

Source: https://gradien.ai/core/docs/harnesses/claude-code/

Claude Code Setup

Claude Code can add remote MCP servers from the command line and complete OAuth through the app's MCP UI.

Claude Code is different from Claude Desktop. Use this page only for Claude Code.

Run the guided installer:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness claude-code

The installer creates a short-lived Core signup/login session, registers Core for Claude Code, and prints any agent-specific next steps.

Core MCP server URL:

https://core.gradien.ai/mcp

Authentication

Claude Code may not show a newly added MCP server inside /mcp until the app restarts.

Use this order:

  1. Finish the installer.
  2. Fully quit and reopen Claude Code, or start a fresh Claude Code session.
  3. Run /mcp.
  4. Select Core.
  5. Choose Authenticate or Connect if prompted.
  6. Approve Core in the browser.

If Core is missing from /mcp before a restart, treat that as a stale Claude Code session rather than a failed install.

Verify

After authentication, Core should appear as a connected MCP server and expose Core tools in a fresh Claude Code session. If tools are still missing, restart Claude Code once more before reinstalling.

---

Claude Web Setup

Source: https://gradien.ai/core/docs/harnesses/claude-web/

Claude Web Setup

Claude web connects to Core through a custom connector in Claude settings. Claude's cloud service must be able to reach the MCP server over public HTTPS.

Core MCP server URL:

https://core.gradien.ai/mcp

Setup

  1. Open Claude in your browser.
  2. Open Settings or Customize.
  3. Go to Connectors.
  4. Choose Add custom connector.
  5. Enter name: Core.
  6. Paste https://core.gradien.ai/mcp.
  7. Approve the Core login or permissions screen.
  8. Start a fresh Claude chat if the connector does not appear in the current chat.

For Team or Enterprise plans, an Owner may need to add the connector under Organization settings first. Members can then connect Core individually from their own Claude connector settings.

Optional CLI Signup

The Core setup CLI can create or link your Core account before you add the connector:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness claude-web

This CLI step is optional for Claude web. The key setting in Claude is still the remote MCP URL above.

Troubleshooting

If Claude shows Authorization with the MCP server failed, check the Core troubleshooting page. Common causes include OAuth metadata, dynamic client registration, redirect URI allowlists, token scopes, or token audience/resource mismatch.

---

Claude Desktop Setup

Source: https://gradien.ai/core/docs/harnesses/claude-desktop/

Claude Desktop Setup

Claude Desktop may support Core through remote custom connectors or through a desktop extension package, depending on the current Claude plan and app version.

Claude Desktop is different from Claude Code. Do not use claude mcp add or Claude Code config commands for Claude Desktop.

Remote Connector

If Claude Desktop offers custom connectors:

  1. Open Claude Desktop.
  2. Open Settings.
  3. Go to Connectors.
  4. Choose Add custom connector.
  5. Name the connector Core.
  6. Paste this URL:
https://core.gradien.ai/mcp
  1. Approve the Core login or permissions screen.
  2. Restart Claude Desktop if the tools do not appear.

Desktop Extension

If your Core account provides a Claude Desktop extension:

  1. Download the Core desktop extension from Core.
  2. Open Claude Desktop.
  3. Open Settings.
  4. Go to Extensions.
  5. Install the downloaded Core extension.
  6. Paste a Core connector key only if Claude Desktop asks for it.
  7. Restart Claude Desktop.

Verify

Open a fresh Claude Desktop chat after setup. Core tools should appear in the available connector/tool list once the connector is loaded and authenticated.

---

ChatGPT Setup

Source: https://gradien.ai/core/docs/harnesses/chatgpt/

ChatGPT Setup

ChatGPT connects to Core through a remote MCP connector. This is configured in ChatGPT settings, not by editing local files.

Core MCP server URL:

https://core.gradien.ai/mcp

Setup

  1. Open ChatGPT.
  2. Open Settings.
  3. Go to Apps, Connectors, or Developer Mode, depending on the current ChatGPT UI.
  4. Add a custom app, custom connector, or remote MCP connector.
  5. Choose Server URL, not Tunnel.
  6. Paste https://core.gradien.ai/mcp.
  7. Choose OAuth for authentication.
  8. Approve Core when ChatGPT opens the login or consent screen.

Use Tunnel only for a private/local MCP server such as localhost, a dev machine, or a server hidden behind a firewall. Hosted Core uses the public HTTPS Server URL path.

If Connection Fails

ChatGPT may show a generic error if the OAuth handshake fails. The most common causes are:

  • OAuth scopes requested by ChatGPT are not allowed by the provider.
  • The ChatGPT redirect URI is not accepted by the authorization server.
  • Dynamic Client Registration or the equivalent client registration path is not available.
  • The issued access token is rejected by the Core MCP server because the token audience, resource, issuer, expiry, or organization claims do not match.

For production Core, do not switch to No Authentication. Core contains user memory and should be protected by OAuth. No Authentication is only appropriate for a separate disposable smoke-test server.

Verify

After ChatGPT says the connector is connected, start a fresh chat and check whether Core tools are available. ChatGPT may expose compatibility tools such as search/fetch as well as standard Core MCP tools, depending on current ChatGPT connector support.

---

Cursor Setup

Source: https://gradien.ai/core/docs/harnesses/cursor/

Cursor Setup

Cursor supports remote MCP servers through Cursor settings and mcp.json. Core should usually be configured globally so it follows you across projects.

Core MCP server URL:

https://core.gradien.ai/mcp

Global config path:

~/.cursor/mcp.json

Project config path:

.cursor/mcp.json

Run the guided installer:

npx -y @gradien/core-agent-setup

The installer creates a Core signup/login session, backs up existing Cursor MCP config, and adds Core where Cursor can load it.

Manual Config

The expected global config shape is:

{
  "mcpServers": {
    "core": {
      "url": "https://core.gradien.ai/mcp"
    }
  }
}

If the file already contains other MCP servers, preserve them and add only the core entry.

Do not put bearer tokens or connector keys in Cursor config unless OAuth is impossible and you intentionally choose that fallback.

Load and Authenticate

Cursor may not hot-load new MCP servers in an existing chat.

  1. Reload Cursor with Cmd+Shift+P -> Developer: Reload Window, or fully quit and relaunch Cursor.
  2. Open Cursor Settings.
  3. Go to Features -> Model Context Protocol.
  4. Find Core. It may appear as core or user-core.
  5. Click Connect or Authenticate.
  6. Approve Core in the browser.

If only an mcp_auth tool is visible, Core is present but not authenticated yet. Complete the OAuth step from Cursor settings or by using the visible auth tool.

If Cursor Hangs During OAuth

If Cursor stays on Waiting for callback... or Exchanging token... after the browser returned to Cursor:

  1. Stop clicking Connect/Allow repeatedly.
  2. Fully quit and relaunch Cursor.
  3. Try Connect once more.
  4. Check Cursor MCP Logs in the Output panel: Cmd+Shift+U -> MCP Logs.

Repeated unauthenticated requests to /mcp mean Cursor can reach Core but did not complete or store OAuth. That is usually an OAuth callback state issue, not a bad URL.

Fallback

If OAuth keeps hanging after one clean relaunch, a scoped Core connector key can be used as a fallback. Store it as locally and narrowly as possible, prefer environment-variable interpolation if Cursor supports it, and rotate the key later.

---

VS Code Setup

Source: https://gradien.ai/core/docs/harnesses/vscode/

VS Code Setup

VS Code and GitHub Copilot use their own MCP server configuration shape. Do not copy Cursor's mcp.json format into VS Code unless the current VS Code docs explicitly say to do so.

Core MCP server URL:

https://core.gradien.ai/mcp

Setup

  1. Open the current VS Code MCP server documentation.
  2. Open the user or workspace MCP configuration location documented by VS Code.
  3. Back up the existing config before editing it.
  4. Add Core using the current VS Code servers shape for remote MCP servers.
  5. Use https://core.gradien.ai/mcp as the server URL.
  6. Save the config.
  7. Approve or start the server if VS Code prompts.

Verify

Open a fresh VS Code/Copilot chat or reload the VS Code window. Core should appear in the MCP server/tool list after VS Code loads the config and completes authentication.

---

Windsurf Setup

Source: https://gradien.ai/core/docs/harnesses/windsurf/

Windsurf Setup

Windsurf/Cascade has its own MCP configuration conventions. Some flows use serverUrl for remote MCP servers.

Core MCP server URL:

https://core.gradien.ai/mcp

Setup

  1. Open the current Windsurf MCP documentation.
  2. Open Windsurf's MCP settings or local MCP config location.
  3. Back up any existing config before editing it.
  4. Add Core using the current Windsurf remote MCP shape.
  5. Use https://core.gradien.ai/mcp as the server URL.
  6. Save the config and reload Windsurf if needed.
  7. Approve OAuth if Windsurf prompts for browser authentication.

Verify

Core should appear in Windsurf/Cascade's MCP server list after reload. If tools do not appear, check for enterprise/admin controls, MCP enablement settings, or tool-count limits in the current Windsurf version.

---

Hermes Setup

Source: https://gradien.ai/core/docs/harnesses/hermes/

Hermes Setup

Hermes Agent has a native MCP client. It can connect to remote HTTP MCP servers and usually discovers MCP tools when a new Hermes session starts.

Core MCP server URL:

https://core.gradien.ai/mcp

Run the guided installer:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness hermes

The direct Hermes command is:

hermes mcp add core --url https://core.gradien.ai/mcp --auth oauth

Prefer the guided installer first because it handles Core signup/login before registration.

Load and Verify

  1. Restart Hermes or start a fresh Hermes session after registration.
  2. Check the MCP server list:
hermes mcp list
  1. Test the Core server if your Hermes version supports it:
hermes mcp test core
  1. If Hermes prompts for OAuth, approve Core in the browser.

Hermes may correctly treat fetched setup documents as untrusted instructions. That is fine. Core setup does not change Hermes identity, policies, SOUL.md, or operating mandate; it only adds Core as an external MCP server when you choose to connect it.

---

OpenCode Setup

Source: https://gradien.ai/core/docs/harnesses/opencode/

OpenCode Setup

OpenCode supports remote MCP server configuration and OAuth. It can prompt for OAuth automatically when the server is first used.

Core MCP server URL:

https://core.gradien.ai/mcp

Run the guided installer:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness opencode

Prefer remote MCP plus OAuth. Do not paste long-lived connector keys into OpenCode config unless OAuth is impossible and you intentionally choose that fallback.

Verify

Check the configured MCP servers:

opencode mcp list

If Core is unauthenticated, stale, or unable to load tools, start the OAuth flow:

opencode mcp auth core

If opencode mcp auth core says Core already has valid credentials, do not re-authenticate unless you intentionally want to replace those credentials. Continue with:

opencode mcp debug core

If OpenCode still reports needs_auth after valid credentials, use one clean reset:

opencode mcp logout core
opencode mcp auth core

Then restart OpenCode or start a fresh OpenCode session.

---

Generic MCP Setup

Source: https://gradien.ai/core/docs/harnesses/generic/

Generic MCP Setup

Use this page for any MCP client that is not listed elsewhere.

Core MCP endpoint:

https://core.gradien.ai/mcp

OAuth protected resource metadata:

https://core.gradien.ai/.well-known/oauth-protected-resource/mcp

Preferred Setup

  1. Add Core as a remote Streamable HTTP MCP server.
  2. Use https://core.gradien.ai/mcp as the server URL.
  3. Let the client discover OAuth from Core protected-resource metadata.
  4. Complete browser consent.
  5. Verify initialize and tools/list.

Fallback

Use a scoped Core connector key only if the client cannot complete OAuth. Connector keys should be personal, scoped, revocable, and stored locally.

Avoid adding long-lived keys to shared project files.

---

Troubleshooting

Source: https://gradien.ai/core/docs/troubleshooting/

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.