Sign in Try Core free

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 connects the knowledge and tools my team already uses, keeps relevant context current as work changes, and makes that context available across compatible AI tools.

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

Generated: 2026-07-24T00:00:00.000Z Canonical index: https://core.gradien.ai/core/llms.txt

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

Core Setup Guide

Generated: 2026-07-24T00:00:00.000Z Sources verified: 2026-07-24

Core connects the knowledge and tools you already use, keeps relevant context current as work changes, and makes that context available across compatible AI tools. This guide explains how to connect Core and start with one recurring workflow.

Human-friendly setup page: https://core.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 connects your existing tools, organizes the information that matters, and makes relevant context available across knowledge, tools, teams, and AI workflows, so sessions in Codex, Claude, ChatGPT, Cursor, and other compatible AI tools 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.

Fastest Setup

Core onboarding treats ChatGPT and Claude as the two ordinary setup choices. It prepares a personalized Secure server address for the chosen app and keeps checking for the connection in the background, so users can finish onboarding without waiting.

ChatGPT

Choose ChatGPT in Core and select Copy address and open ChatGPT. Core copies the complete personalized address and opens https://chatgpt.com/plugins.

  1. In ChatGPT Settings, select Plugins, scroll to Developer mode at the bottom, and enable it.
  2. Open Plugins and choose Create app (or Browse plugins → + if your account shows that path), then create Core.
  3. Choose Server URL, paste the address copied by Core, choose OAuth, and approve the connection.

Keep the setup_attempt query parameter in the copied address. Full current instructions: https://core.gradien.ai/core/docs/harnesses/chatgpt.md

Claude

Choose Claude in Core and select Open Claude. Core opens Anthropic's connector page with the name and personalized address already filled in. Review the details, select Add, and approve Core.

The connector belongs to the signed-in Claude account, so it is available across Claude on the web, Desktop, and mobile. Do not install it separately in each Claude app. Full current instructions: https://core.gradien.ai/core/docs/harnesses/claude-web.md

More Ways To Connect

Developer and local AI tools remain available under More ways to connect. Identify the app, open its guide, and use its documented setup path. This may be an app setting, a supported command, or a configuration file.

An agent can help with those steps. Paste:

Please help me set up Core. Core connects the knowledge and tools my team already uses, keeps relevant context current as work changes, and makes that context available across compatible AI tools. Use this official setup reference: https://core.gradien.ai/core/docs/reference

If the agent cannot safely run commands or edit settings, it should give one short human step at a time.

A guided terminal helper is also available:

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

Do not keep retrying the helper if npx, npm, or package execution is unavailable. Use the app-specific guide instead.

Setup Guides

Start Here

More Ways To Connect

During onboarding, always keep the complete personalized address, including setup_attempt, so Core can recognize the exact connection. Outside onboarding, the standard address is https://core.gradien.ai/mcp/continuity and OAuth is the normal authentication choice. The shorter https://core.gradien.ai/mcp address exposes an advanced server and is not the default onboarding address.

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

How To Use Core After Setup

Once connected, Core can support normal AI work without requiring users to mention it in every prompt. Its visible application surfaces still provide a place to review context, organize work, manage access, and begin from the latest state. 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

  • Human-friendly setup page: https://core.gradien.ai/core/docs
  • Personal-context MCP endpoint: https://core.gradien.ai/mcp/continuity
  • Advanced full MCP endpoint: https://core.gradien.ai/mcp
  • OAuth protected resource metadata: https://core.gradien.ai/.well-known/oauth-protected-resource/mcp/continuity
  • Agent-readable summary: https://core.gradien.ai/core/llms.txt
  • Full agent-readable context: https://core.gradien.ai/core/llms-full.txt
  • What Core is: https://core.gradien.ai/core/docs/what-is-core.md
  • Why Core matters: https://core.gradien.ai/core/docs/why-core.md
  • How to use Core: https://core.gradien.ai/core/docs/how-to-use-core.md
  • FAQ: https://core.gradien.ai/core/docs/faq.md

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

What Is Core

Core keeps the context behind AI-assisted work connected across files, decisions, people, projects, and AI tools. Agent checkpoints, drafts, decisions, tasks, skills, memory, and saved work can persist beyond a single session.

The key idea is simple: agents, models, and harnesses change. Useful context should not disappear when you move between connected tools.

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 works with the tools and AI people already use, keeping approved context available as work changes. Teams can also add shared company material for agents to reference, but agents should only change shared material when explicitly asked.

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

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 connected agents durable context, 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 later work
  • 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.

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

How To Use Core

Once connected, Core can support ordinary AI-assisted work without requiring users to mention it in every prompt. The Core application remains the place where users review information, organize work, manage access, retain useful outputs, and see what has been prepared or carried forward.

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 agent should handle the Core loop internally:

  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.

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

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?

Core works alongside ChatGPT, Claude, Codex, Cursor, and other compatible AI tools. It gives connected tools access to relevant information the user is allowed to see and lets useful results be saved back, without replacing the AI tools themselves. 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 an agent start?

Ask the user to paste: "Please help me set up Core. Core connects the knowledge and tools my team already uses, keeps relevant context current as work changes, and makes that context available across compatible AI tools. Use this official setup reference: https://core.gradien.ai/core/docs/reference". The reference includes native app-specific connection paths and the guided CLI fallback.

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

Codex Setup

Source checked: 2026-07-24 Official source: https://developers.openai.com/codex/mcp

Codex Desktop, the CLI, and the IDE extension share MCP configuration on the same host. Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

Open ~/.codex/config.toml, or a trusted project's .codex/config.toml, and add:

[mcp_servers.core]
url = "<secure-server-address>"
auth = "oauth"

Then run:

codex mcp login core
codex mcp list

Approve Core in the browser, then restart Codex or open a fresh task so the tools load. A localhost callback after approval is normal because Codex receives the one-time OAuth code on the local machine.

Do not add a custom OAuth resource or narrow Core's scopes. Codex reads the protected-resource metadata and prefers the server-advertised scopes.

If a fresh Codex task still reports authentication required, run codex mcp logout core, then codex mcp login core once. Do not extract or edit Codex's stored OAuth tokens.

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

Claude Code Setup

Source checked: 2026-07-24 Official source: https://docs.anthropic.com/en/docs/claude-code/mcp

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

Run the native remote HTTP setup command, replacing the placeholder with the full address shown in Core:

claude mcp add --transport http core '<secure-server-address>'

Then start a fresh Claude Code session, run /mcp, select Core, and approve the browser login if prompted. A newly added server may not appear in the already-running session.

Use the --scope user option if Core should be available across all projects supported by the current Claude Code version. Keep the default project or local scope when the user wants a narrower setup.

Do not substitute Claude Desktop instructions here. Claude Code uses its own MCP configuration and command-line client.

If Core is still missing after a full restart, inspect claude mcp list before adding another entry. Duplicate registrations make authentication recovery harder.

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

Connect Core to Claude

Source checked: 2026-07-24 Official source: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp

Core is an account-level Claude connector. Add it once and it is available for the same signed-in account across Claude on the web, Desktop, and mobile.

Open Claude from Core

During Core onboarding, choose Claude and select Open Claude. Core opens Anthropic's official connector page with the name and your personalized Secure server address already filled in.

  1. Review the prefilled name and address.
  2. Select Add.
  3. Approve Core when the sign-in window opens.
  4. Return to Core. The Claude status changes to Connected after Claude makes its first authenticated context check. You can finish onboarding while Core waits.

Keep the full personalized address, including its setup_attempt query parameter. It lets Core recognize this exact onboarding connection.

Manual fallback

If the prefilled page does not open, open Claude Settings, choose Connectors, select Add custom connector, and enter:

  • Name: Core
  • Remote MCP server URL: the complete Secure server address shown by Core

Select Add and approve Core. Outside onboarding, use https://core.gradien.ai/mcp/continuity.

No local process or configuration file is required. If Core is already connected to this Claude account, do not install it again for Claude Desktop or mobile. Start a new conversation if Core does not appear immediately.

For Anthropic's current behavior and availability, see Get started with custom connectors and Directory versus custom connectors.

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

Use Core in Claude Desktop

Source checked: 2026-07-24 Official source: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp

Claude Desktop uses the same account-level connectors as Claude on the web and mobile. If you connected Core from onboarding or Claude web under the same account, there is nothing else to install.

Open a new conversation in Claude Desktop and check that Core is available. If it does not appear, restart Claude Desktop and confirm that you are signed in to the same Claude account.

If Core is not connected to the account yet, follow the Claude setup guide. During onboarding, use Core's Open Claude action so the connector name and personalized address are already filled in. The manual Remote MCP server URL flow is only a fallback.

Do not use claude mcp add for Claude Desktop. That command configures Claude Code, which is a separate developer client.

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

Connect Core to ChatGPT

Source checked: 2026-07-24 Official source: https://developers.openai.com/plugins/deploy/connect-chatgpt

During Core onboarding, choose ChatGPT and select Copy address and open ChatGPT. Core copies your personalized Secure server address and opens https://chatgpt.com/plugins. Keep the full address on your clipboard, including its setup_attempt query parameter, so Core can recognize this exact connection.

1. Turn on Developer mode

  1. Open ChatGPT Settings.
  2. Select Plugins.
  3. Scroll to Developer mode at the bottom and enable it.

2. Add Core

  1. Open Plugins and choose Create app (or Browse plugins → + if your account shows that path).
  2. Enter Core for the name.
  3. Add a short description, such as Keeps my working context available across AI tools.
  4. Under Connection, choose Server URL.
  5. Paste the complete Secure server address copied by Core.
  6. Under Authentication, choose OAuth.

3. Approve the connection

  1. Accept ChatGPT's acknowledgement and create the plugin.
  2. Approve Core when the sign-in window opens.
  3. Return to Core. The ChatGPT status changes to Connected after ChatGPT makes its first authenticated context check, which can take a few seconds. You can finish onboarding while Core waits.

Troubleshooting

Use Server URL, not Tunnel. Core is already available online; Tunnel is for a server running on a private network or local computer.

If the URL is missing or no longer works, return to Core and reopen ChatGPT setup. Core will prepare a fresh personalized address when needed. Outside onboarding, the standard address is https://core.gradien.ai/mcp/continuity; the shorter /mcp address is an advanced server and is not the normal setup choice.

If the callback contains invalid_scope and says the client cannot request openid, report the complete callback URL once. Creating duplicate plugins will not fix an authorization-server error.

For OpenAI's current setup requirements, see Connect your MCP server to ChatGPT.

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

Cursor Setup

Source checked: 2026-07-24 Official source: https://docs.cursor.com/en/tools/mcp

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core in Cursor

  1. Open Cursor Settings.
  2. Open Tools & MCPs.
  3. If Cursor shows a migration notice, select Open Tools & MCPs in Customize.
  4. Select New MCP Server or Add a Custom MCP Server.
  5. Enter Core and paste the complete Core address.
  6. Connect and approve Core in the browser.
  7. Reload Cursor or run Developer: Reload Window if Core remains disabled.

For global manual configuration, preserve the other entries in ~/.cursor/mcp.json and add:

{
  "mcpServers": {
    "core": {
      "url": "<secure-server-address>"
    }
  }
}

Use the global config when Core should follow the user across projects. Use .cursor/mcp.json only for a project-scoped setup.

If Cursor remains on Waiting for callback or Exchanging token after approval, quit and relaunch Cursor once, then inspect Output, MCP Logs. Do not keep creating duplicate Core entries or paste a long-lived connector key into the file during normal setup.

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

VS Code Setup

Source checked: 2026-07-24 Official source: https://code.visualstudio.com/docs/agent-customization/mcp-servers

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

  1. Open the Command Palette.
  2. Run MCP: Add Server.
  3. Choose HTTP.
  4. Paste the complete Core address.
  5. Enter core as the server ID.
  6. Choose User when Core should be available across projects, or Workspace for the current repository only.
  7. Start the server and approve Core in the browser when prompted.

The equivalent VS Code MCP configuration uses the servers shape:

{
  "servers": {
    "core": {
      "type": "http",
      "url": "<secure-server-address>"
    }
  }
}

Do not reuse Cursor's mcpServers wrapper in VS Code. The two editors use different configuration shapes.

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

Windsurf Setup

Source checked: 2026-07-24 Official source: https://docs.windsurf.com/windsurf/cascade/mcp

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

  1. Open Cascade.
  2. Select the MCPs icon in the top-right corner, or open Windsurf Settings, Cascade, MCP Servers.
  3. Choose Add custom MCP server.
  4. Enter Core and paste the complete Core address.
  5. Save, then approve Core in the browser.
  6. Refresh the MCP list or restart Windsurf if the tools do not appear.

For manual configuration, preserve existing servers in ~/.codeium/windsurf/mcp_config.json and use Windsurf's remote serverUrl form:

{
  "mcpServers": {
    "core": {
      "serverUrl": "<secure-server-address>"
    }
  }
}

Use Streamable HTTP and OAuth. Do not add a connector key unless the current Windsurf release cannot complete OAuth and the user deliberately chooses that fallback.

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

Hermes Setup

Source checked: 2026-07-24 Official source: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

Run:

hermes mcp add core --url '<secure-server-address>' --auth oauth
hermes mcp login core

Approve Core in the browser from a fresh terminal, then restart Hermes or run /reload-mcp.

The equivalent ~/.hermes/config.yaml entry is:

mcp_servers:
  core:
    url: "<secure-server-address>"
    auth: oauth

If Hermes asks which tools to enable, run hermes mcp configure core and keep the default Core context tools enabled. This connection does not replace Hermes's identity, system instructions, or safety policy.

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

OpenCode Setup

Source checked: 2026-07-24 Official sources: https://opencode.ai/docs/mcp-servers/ and https://opencode.ai/docs/cli/

Use the complete Secure server address shown by Core during onboarding, including ?setup_attempt=.... Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

Add Core to either your global ~/.config/opencode/opencode.json or a project's opencode.json. Merge the mcp.core entry into the existing JSON instead of replacing the rest of the file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "core": {
      "type": "remote",
      "url": "<secure-server-address>",
      "enabled": true
    }
  }
}

Alternatively, run the documented interactive wizard:

opencode mcp add

Choose a remote server, name it core, and paste the complete Secure server address when prompted. OpenCode starts OAuth automatically when Core is first used; you can trigger it explicitly with opencode mcp auth core. Verify with opencode mcp list, then restart OpenCode if the tools do not appear.

If OpenCode says valid credentials already exist, do not reauthenticate unless the existing token is actually failing.

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

Generic MCP Setup

Source checked: 2026-07-24 Protocol source: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization

Use this guide for a client without a dedicated Core setup page.

During onboarding, paste the complete Secure server address shown by Core. It ends in /mcp/continuity?setup_attempt=...; keep the query parameter so Core can verify the connection. Outside onboarding, use https://core.gradien.ai/mcp/continuity.

Add Core

  1. Add Core as a remote Streamable HTTP MCP server.
  2. Use OAuth and let the client discover authorization through Core's protected-resource metadata.
  3. Complete browser consent.
  4. Verify MCP initialize and tools/list.

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

The /mcp endpoint exposes Core's broader advanced server. Use /mcp/continuity for the personal-context experience described in onboarding.

Use a personal, scoped, revocable connector key only when the client cannot complete OAuth and the user deliberately approves a local secret fallback.

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

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.