# Core Agent-Readable Context 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: ```text 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: ```bash 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 - [ChatGPT](https://core.gradien.ai/core/docs/harnesses/chatgpt.md) - [Claude](https://core.gradien.ai/core/docs/harnesses/claude-web.md) - [Claude Desktop](https://core.gradien.ai/core/docs/harnesses/claude-desktop.md) - no separate installation when Core is already connected to the same Claude account ### More Ways To Connect - [Codex](https://core.gradien.ai/core/docs/harnesses/codex.md) - [Claude Code](https://core.gradien.ai/core/docs/harnesses/claude-code.md) - [Cursor](https://core.gradien.ai/core/docs/harnesses/cursor.md) - [VS Code / Copilot](https://core.gradien.ai/core/docs/harnesses/vscode.md) - [Windsurf / Devin Cascade](https://core.gradien.ai/core/docs/harnesses/windsurf.md) - [Hermes](https://core.gradien.ai/core/docs/harnesses/hermes.md) - [OpenCode](https://core.gradien.ai/core/docs/harnesses/opencode.md) - [Generic compatible clients](https://core.gradien.ai/core/docs/harnesses/generic.md) 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/` 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: ```toml [mcp_servers.core] url = "" auth = "oauth" ``` Then run: ```bash 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: ```bash claude mcp add --transport http core '' ``` 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [Directory versus custom connectors](https://claude.com/docs/connectors/building/directory-vs-custom). --- 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](https://core.gradien.ai/core/docs/harnesses/claude-web.md). 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](https://developers.openai.com/plugins/deploy/connect-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: ```json { "mcpServers": { "core": { "url": "" } } } ``` 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: ```json { "servers": { "core": { "type": "http", "url": "" } } } ``` 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: ```json { "mcpServers": { "core": { "serverUrl": "" } } } ``` 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: ```bash hermes mcp add core --url '' --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: ```yaml mcp_servers: core: url: "" 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: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "core": { "type": "remote", "url": "", "enabled": true } } } ``` Alternatively, run the documented interactive wizard: ```bash 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 ` 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/` 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 ` 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.