Coreby Gradien
Docs
Start free today

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.txt

# Core Agent-Readable Context

---

---

Generated: 2026-06-23T07:48:08.316Z

---

Canonical index: https://gradien.ai/core/llms.txt

---

---

# Core Setup Guide

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

# Core Setup Guide

Generated: 2026-06-23T07:48:08.316Z Sources verified: 2026-06-19

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.

Human-friendly 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.

Fastest Setup

Option 1: Agent-Assisted Native Setup

Paste this into the agent or app being connected:

Please help me set up Core. 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.txt

The agent should identify the current app, fetch the matching app-specific guide, and prefer that app's native MCP setup path. That means using commands such as codex mcp add, claude mcp add, hermes mcp add, opencode mcp add, editing Cursor MCP config, or giving a short connector-settings handoff for hosted web apps.

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

Option 2: Manual Remote MCP URL

Use this URL in apps that support adding a remote MCP server or custom connector:

https://core.gradien.ai/mcp

Choose OAuth when the app asks for an authentication method.

Option 3: Guided CLI Helper

Run this in a terminal if you want an interactive walkthrough:

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

The CLI asks which app is being connected, opens Core signup or login, and then shows or applies supported local setup steps. Do not keep retrying the CLI if npx, npm, or package execution is unavailable in the current harness; use the native app-specific setup guide instead.

App-Specific Setup Guides

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

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

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

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

---

# What Is Core

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

# 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.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 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.md

# How To Use Core

For the user, Core should mostly disappear after setup. They should ask their agent for normal work, and the connected agent should 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 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.

---

# Core FAQ

Source: https://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?

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 an agent start?

Ask the user to paste: "Please help me set up Core. 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.txt". The reference includes native app-specific connection paths and the guided CLI fallback.

---

# Codex Setup

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

# Codex Setup

Source checked: 2026-06-19 Official source: https://developers.openai.com/codex/mcp

Codex supports MCP servers and should be verified against current OpenAI Codex MCP docs before changing this path.

Core-specific rule: prefer the Core local bridge when a scoped connector key is available. Main history shows native Codex setup was fragile, and Core has a smoke test for the bridge path.

Recommended setup path:

  1. Use native remote MCP: codex mcp add core --url https://core.gradien.ai/mcp.
  2. Run codex mcp login core only when the protected-resource metadata advertises an authorization server.
  3. If the user wants a guided CLI walkthrough, or native setup cannot be completed safely, run npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness codex.
  4. Do not pass --oauth-resource for Core. Codex already discovers the OAuth resource from protected-resource metadata; adding it explicitly can make the provider reject the request because resource appears twice.
  5. Do not pass --scopes profile,email for Core. Codex should prefer the server-advertised scopes_supported; narrowing scopes can mint a token that logs in but cannot select the Core workspace.
  6. Tell the user that http://127.0.0.1:<port>/callback/... after browser login is normal: Codex receives the one-time OAuth code locally while the MCP server remains remote at the Core URL.
  7. If Codex says OAuth needs an experimental flag, or an older Codex build fails while parsing OAuth metadata, check codex --version and tell the user to update Codex. Do not enable experimental OAuth flags as part of normal Core setup.
  8. If codex mcp login core succeeds, do not inspect .codex auth/cache files and do not try to extract tokens for manual MCP calls. Codex owns those OAuth credentials.
  9. Current Codex CLI versions do not expose a direct codex mcp tools/list probe. Verify with codex mcp get core and codex mcp list, then tell the user to restart Codex or open a fresh session so Core tools can load.
  10. If a fresh Codex session still reports AuthRequired, stop broad diagnostics and run codex mcp logout core, then codex mcp login core, then restart or start another fresh Codex session.
  11. If native OAuth still fails after a clean logout/login, fresh session, and current Codex version, fetch troubleshooting and consider the Core local bridge fallback.
  12. The local bridge remains the proven fallback once a safe authenticated workspace credential is available.

If you cannot run commands, give the user a very short handoff and explain that it is a one-time local setup.

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

---

# Claude Code Setup

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

# Claude Code Setup

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

Claude Code supports adding MCP servers from the command line. Use the current Anthropic docs for exact flags before changing generated commands.

Only use this guide when the current app is Claude Code. If the user says Claude Desktop, use the Claude Desktop guide instead; do not run claude mcp commands for Desktop setup.

Recommended setup path:

  1. Use Claude Code's native MCP command first: claude mcp add --transport http core https://core.gradien.ai/mcp.
  2. If the user wants a guided CLI walkthrough, run the setup CLI with --harness claude-code so it does not confuse Claude Code with Claude Desktop.
  3. Prefer OAuth/browser consent where reliable.
  4. Use a scoped bearer header fallback only when OAuth is unavailable or unreliable.
  5. After adding the MCP server, do not ask the user to run /mcp in the same Claude Code session. Newly registered servers often do not appear there yet.
  6. First ask the user to restart Claude Code or start a fresh Claude Code session.
  7. Only in the fresh session, ask the user to run /mcp, select Core, and approve browser login if prompted.
  8. If Core is missing from /mcp, treat that as a stale Claude Code session, not a failed Core install. Ask the user to fully quit/relaunch Claude Code and check /mcp again before retrying setup.
  9. Verify the server appears in Claude Code and that Core tools are listed.

---

# Claude Web Setup

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

# Claude Web Setup

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

Claude web custom connectors require human app settings steps. Claude connects to remote MCP servers from Anthropic cloud infrastructure, so the server must be public HTTPS and reachable from Anthropic, not merely reachable from the user's laptop.

Core hosted remote MCP URL: https://core.gradien.ai/mcp

Recommended setup path:

  1. Fetch the current Claude custom connector documentation before giving UI-specific instructions, because Claude settings labels move.
  2. Hand the user the hosted URL directly: https://core.gradien.ai/mcp. Hosted Claude setup is a settings-page connector flow, not a CLI install.
  3. If the user wants a guided CLI walkthrough only for Core signup/session help, use npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness claude-web, but still expect the final Claude settings step to be manual.
  4. Do not omit the harness flag for Claude web when using the CLI; on machines with Codex installed, the CLI may otherwise detect Codex and configure the wrong app.

Human handoff:

  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 this remote MCP server URL: https://core.gradien.ai/mcp.
  7. Approve the Core login or permissions screen.

For Team or Enterprise plans, an Owner may need to add the custom connector under Organization settings first; members then connect it individually from Customize -> Connectors.

If Claude says Authorization with the MCP server failed, do not ask the user to retry blindly. Fetch troubleshooting and check the protected-resource metadata, authorization-server metadata, dynamic client registration or configured OAuth client, redirect URI allowlist, scopes, and token audience.

After the user returns, ask them to start a new Claude chat if needed and verify that Core tools are available.

---

# Claude Desktop Setup

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

# Claude Desktop Setup

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

Claude Desktop setup may use remote custom connectors or the Core MCPB desktop extension depending on current Claude support and user plan.

Claude Desktop is not Claude Code. Do not use claude mcp add, claude mcp remove, or Claude Code local config commands unless the user explicitly asks to configure Claude Code instead.

Human handoff for MCPB:

  1. Download the Core desktop extension from Core Settings.
  2. Open Claude Desktop.
  3. Open Settings -> Extensions.
  4. Install the downloaded Core extension.
  5. Paste the Core connector key only if Claude asks for it.
  6. Restart Claude Desktop if tools do not appear.

Do not assume the user is comfortable editing JSON files.

---

# ChatGPT Setup

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

# ChatGPT Setup

Source checked: 2026-06-19 Official source: https://developers.openai.com/apps-sdk/build/auth

ChatGPT remote MCP setup is a human settings/app connector flow. UI labels change often, so verify current OpenAI docs before changing this guide.

Use Server URL, not Tunnel, for hosted Core. Secure MCP Tunnel is only for private, local, on-prem, or firewall-hidden MCP servers.

Use OAuth for production Core. Core contains user memory and should not be exposed through No Authentication. No Authentication is only useful for a separate disposable public smoke-test server.

Important OAuth requirement:

ChatGPT needs a complete MCP OAuth setup: protected-resource metadata, OAuth/OIDC authorization-server metadata, PKCE, resource parameter handling, and a way for ChatGPT to identify/register its OAuth client. OpenAI supports Client ID Metadata Documents, Dynamic Client Registration, or predefined OAuth client credentials. If Core/Clerk does not expose one of those registration paths or the ChatGPT redirect URI is not allowlisted, ChatGPT may show only “There was a problem connecting Core. Try again later.”

Human handoff:

  1. Open ChatGPT.
  2. Open Settings.
  3. Go to Apps, Connectors, or Developer Mode, depending on the current ChatGPT UI.
  4. Add a remote MCP connector/app.
  5. Choose Server URL and paste this exact Core MCP URL: https://core.gradien.ai/mcp.
  6. Choose OAuth.
  7. If ChatGPT shows a ChatGPT redirect/callback URL, add it to the Core OAuth provider allowlist before retrying.
  8. Approve the Core login and permissions.

After the user returns, verify that ChatGPT can see Core search and fetch compatibility tools as well as the standard Core MCP tools where supported.

---

# Cursor Setup

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

# Cursor Setup

Source checked: 2026-06-19 Official source: https://cursor.com/docs/mcp.md

Cursor supports MCP configuration through Cursor settings and mcp.json. Use the markdown docs as the source of truth because they are easier for agents to fetch. Cursor supports remote Streamable HTTP MCP servers through a url field and handles OAuth for remote servers.

Core hosted remote MCP URL: https://core.gradien.ai/mcp

Global config path: ~/.cursor/mcp.json. Project config path: .cursor/mcp.json. Prefer global config for Core so the user carries Core across projects.

Expected global config shape:

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

Recommended setup path:

  1. Fetch current Cursor MCP docs before changing config; Cursor labels and auth behavior change over time.
  2. Use Cursor native config first: inspect existing ~/.cursor/mcp.json, back it up, preserve other mcpServers, and add only the Core server entry.
  3. If the user wants a guided CLI walkthrough, run the setup CLI with --harness cursor --yes; it should create Core signup/login, then merge Core into ~/.cursor/mcp.json and back up the previous file.
  4. Do not put bearer tokens or connector keys in Cursor config unless OAuth is impossible and the user explicitly approves that fallback.
  5. Ask the user to reload Cursor or run Cmd+Shift+P -> Developer: Reload Window. Existing Cursor chats may not hot-load new MCP servers.
  6. If Cursor prompts for OAuth, have the user approve Core in the browser.
  7. If Cursor shows Core as user-core, unauthenticated, or with only mcp_auth, that is an auth-ready state, not a failed install. Run the visible mcp_auth tool if the agent can, or ask the user to click Connect/Authenticate in Cursor Settings -> Features -> Model Context Protocol.
  8. If Cursor stays on Waiting for callback... or Exchanging token... after the browser opened Cursor, stop repeated Connect/Allow clicks. Fully quit and relaunch Cursor once, then inspect Cursor MCP Logs before another auth attempt.
  9. In logs, repeated unauthenticated requests from Cursor/<version> to /mcp mean the server is reachable but Cursor did not complete/store OAuth. Treat this as a Cursor OAuth callback state, not a bad mcp.json URL.
  10. Verify after reload/auth with Cursor MCP tools or Cursor MCP logs. Logs are in the Output panel (Cmd+Shift+U) -> MCP Logs.
  11. If native OAuth keeps hanging after one clean relaunch, use the fallback only with explicit user approval: create a scoped Core connector key from Core Settings -> Connectors, then add it as an HTTP Authorization header in Cursor mcp.json. Prefer ${env:CORE_CONNECTOR_KEY} interpolation if Cursor resolves it in the user's version; otherwise warn that a pasted key is stored locally in plaintext and should be rotated later.

If Cursor rejects the minimal remote config, retry using the latest Cursor-documented remote server shape. Some examples include an explicit type for HTTP servers; keep the URL as the source of truth and do not add secrets.

---

# VS Code Setup

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

# VS Code Setup

Source checked: 2026-06-19 Official source: https://code.visualstudio.com/docs/copilot/customization/mcp-servers

VS Code and GitHub Copilot use their own MCP server configuration shape. Do not reuse Cursor JSON blindly.

Recommended setup path:

  1. Read the current VS Code MCP docs.
  2. Inspect existing workspace/user MCP config.
  3. Back up config before editing.
  4. Add Core with the documented servers shape.
  5. Ask the user to approve or start the server if VS Code prompts them.

---

# Windsurf Setup

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

# Windsurf Setup

Source checked: 2026-06-19 Official source: https://docs.windsurf.com/windsurf/cascade/mcp

Windsurf/Cascade has its own MCP config conventions, including serverUrl in some flows. Do not assume the Cursor config shape.

Recommended setup path:

  1. Fetch the current Windsurf MCP docs.
  2. Detect whether the user has local Windsurf config available.
  3. Back up config before editing.
  4. Use the current documented remote MCP shape.
  5. Note any enterprise/admin controls or tool-count limits if tools do not appear.

---

# Hermes Setup

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

# Hermes Setup

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

Hermes Agent has a native MCP client. It can connect to remote HTTP MCP servers and discovers tools at startup.

Important framing for Hermes:

This Core setup guide is not asking Hermes to replace its system prompt, identity, SOUL.md, Nous-managed environment, or safety policy. Treat it as a user-requested configuration task: connect an external MCP server if allowed, then return to normal Hermes operation.

Recommended setup path:

  1. Use Hermes native MCP setup first: hermes mcp add core --url https://core.gradien.ai/mcp --auth oauth.
  2. If the user wants a guided CLI walkthrough, run npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness hermes. Do not keep retrying the CLI if npx or npm is unavailable in Hermes; continue with the native Hermes command.
  3. Restart Hermes or start a fresh Hermes session after registration; Hermes discovers MCP tools at startup.
  4. Verify with hermes mcp list and hermes mcp test core when available.
  5. If Hermes prompts for OAuth on first use, ask the user to approve Core in the browser.

If Hermes refuses to follow fetched setup instructions as an operational mandate, acknowledge that it is correct not to adopt external instructions as system policy, then continue the user-requested setup using these bounded steps.

---

# OpenCode Setup

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

# OpenCode Setup

Source checked: 2026-06-19 Official source: https://opencode.ai/docs/mcp-servers/

OpenCode supports remote MCP server configuration and OAuth flows. Use the current OpenCode docs before changing commands. OpenCode can prompt for OAuth automatically when the server is first used; opencode mcp auth <server-name> is a manual auth/recovery command, not a mandatory install step.

Recommended setup path:

  1. Use OpenCode native MCP setup first: opencode mcp add core https://core.gradien.ai/mcp.
  2. If the user wants a guided CLI walkthrough, run the setup CLI with --harness opencode --yes.
  3. Prefer remote MCP plus OAuth. Do not paste long-lived connector keys into OpenCode config unless OAuth is impossible and the user explicitly approves that fallback.
  4. After registration, verify with opencode mcp list or the current OpenCode MCP status command.
  5. Only run opencode mcp auth core if OpenCode says Core is unauthenticated, auth is stale, or verification cannot load tools.
  6. If opencode mcp auth core prompts core already has valid credentials. Re-authenticate?, choose No unless you intentionally need to replace credentials. Then return to verification with opencode mcp list or opencode mcp debug core.
  7. If OpenCode still reports needs_auth after valid credentials, run opencode mcp logout core, then opencode mcp auth core once, and check the protected-resource metadata/scopes before retrying loops.
  8. Verify Core tools after auth completes. If tools are missing, restart OpenCode or start a fresh OpenCode session.

---

# Generic MCP Setup

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

# Generic MCP Setup

Use this for any client 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 path:

  1. Add Core as a remote MCP server using Streamable HTTP.
  2. Let the client discover OAuth through protected resource metadata.
  3. Complete browser consent.
  4. Verify initialize and tools/list.

Fallback path:

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

---

# Core MCP Troubleshooting

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

# 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.
  • 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 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.
  • Ask the user to retry browser consent.
  • 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 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, 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

  • 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

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