# Core Agent-Readable Context Canonical index: https://gradien.ai/core/llms.txt Setup page: https://gradien.ai/core/docs Remote MCP endpoint: https://core.gradien.ai/mcp --- ## Core Agent Setup Reference Source: https://gradien.ai/core/docs/reference # Core Agent Setup Reference Core is a personal cloud home base for AI agent work. It keeps memory, files, decisions, tasks, drafts, and working context synced across tools, harnesses, and models. Personal work is private by default. Shared Spaces are available for teams, classes, companies, and projects when the user chooses to collaborate. Use this document as setup reference material. The setup request should come from the user in the chat or app where Core is being connected. ## Core MCP Endpoint ```text https://core.gradien.ai/mcp ``` ## Recommended Setup If the app or agent has shell access, run the guided CLI installer: ```bash npx -y @gradien/core-agent-setup ``` The installer asks which app is being connected, opens Core signup or login, and then applies or explains the agent-specific setup path. Some apps can be configured automatically. Hosted web apps usually require one settings-page connector step. ## ChatGPT Web And Claude Web Setup For hosted web apps, the main setup value is the Core remote MCP server URL: ```text https://core.gradien.ai/mcp ``` In ChatGPT web or Claude web, open the app's connector settings and add a custom connector. In most cases the URL is enough. If the app asks for more fields, use: - Name: `Core` - Description: `Personal cloud memory and files for AI agent work.` - Authentication: `OAuth` Approve the Core login when the browser opens. Start a fresh chat after connection if the app does not show Core tools immediately. If the app cannot run shell commands, use the matching agent-specific guide below. ## Agent-Specific Guides OpenAI: - Codex Desktop: https://gradien.ai/core/docs/harnesses/codex.md - Codex CLI: https://gradien.ai/core/docs/harnesses/codex.md - ChatGPT: https://gradien.ai/core/docs/harnesses/chatgpt.md Anthropic: - Claude Code Desktop: https://gradien.ai/core/docs/harnesses/claude-code.md - Claude Code CLI: https://gradien.ai/core/docs/harnesses/claude-code.md - Claude web: https://gradien.ai/core/docs/harnesses/claude-web.md - Claude Desktop: https://gradien.ai/core/docs/harnesses/claude-desktop.md Editors and IDE agents: - Cursor: https://gradien.ai/core/docs/harnesses/cursor.md - VS Code / Copilot: https://gradien.ai/core/docs/harnesses/vscode.md - Windsurf / Devin Cascade: https://gradien.ai/core/docs/harnesses/windsurf.md Other agent harnesses: - Hermes: https://gradien.ai/core/docs/harnesses/hermes.md - OpenCode: https://gradien.ai/core/docs/harnesses/opencode.md - Generic MCP clients: https://gradien.ai/core/docs/harnesses/generic.md Troubleshooting: https://gradien.ai/core/docs/troubleshooting.md ## Human Steps To Expect Most setup flows have one unavoidable human step: approving a Core signup, login, connector, or restart in the app being connected. For hosted web apps, the remote MCP server URL is: ```text https://core.gradien.ai/mcp ``` ## After Setup Core should fade into the background. Users can keep asking for normal work while connected agents use Core when durable context helps: - 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. Agents should not train users to invoke Core manually for every task. Core is meant to make work more continuous after one-time setup. ## More Product Context - 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 - Rendered setup docs: https://gradien.ai/core/docs - Full agent-readable context: https://gradien.ai/core/llms-full.txt --- ## Core Setup Guide Source: https://gradien.ai/core/docs/guide.md # Core Setup Guide Core gives AI agents a private cloud home for memory, context, decisions, drafts, and checkpoints. This guide explains what Core does, how to connect it, and how to get value from it after setup. Setup page: https://gradien.ai/core/docs Use this page as product documentation. Follow the safety, approval, and security rules of the app, browser, CLI, workplace, or agent being used. ## What Core Gives You Core is personal cloud memory for agent work. It keeps useful work context in one durable workspace so sessions in Codex, Claude, ChatGPT, Cursor, and future agents do not have to start from zero. Core can preserve: - decisions and rationale - drafts, notes, and working context - project files and reference material - tasks, follow-ups, and checkpoints - reusable skills and saved outcomes The default behavior is personal. Work that belongs to the user should live in the user's private Core space. Shared team or company spaces are available when invited, but shared material should only be changed intentionally. ## Best Setup Path Paste this request into the agent or app being connected: ```text Please help me set up Core for this agent. Core is a home base for AI agents: it keeps memory, files, decisions, tasks, and work context synced across tools, harnesses, and models. Use this official setup reference: https://gradien.ai/core/docs/reference ``` This keeps the setup request explicit and user-authored. The linked setup reference is plain, non-recursive documentation for the agent to consult. ## Manual Setup Options ### Guided CLI Setup Run this in a terminal: ```bash npx -y @gradien/core-agent-setup ``` The installer asks which app is being connected, opens Core signup or login, and then shows or applies the setup steps for that app. Some apps can be configured automatically. Hosted web apps usually require a settings-page step. ## ChatGPT Web And Claude Web Setup For hosted web apps, the main setup value is the Core remote MCP server URL: ```text https://core.gradien.ai/mcp ``` In ChatGPT web or Claude web, open the app's connector settings and add a custom connector. In most cases the URL is enough. If the app asks for more fields, use: - Name: `Core` - Description: `Personal cloud memory and files for AI agent work.` - Authentication: `OAuth` Approve the Core login when the browser opens. Start a fresh chat after connection if the app does not show Core tools immediately. ## Agent-Specific Setup Guides Use the guide for the app being connected. These pages contain the agent-specific commands, settings locations, restart behavior, and troubleshooting notes. OpenAI: - Codex Desktop: https://gradien.ai/core/docs/harnesses/codex.md - Codex CLI: https://gradien.ai/core/docs/harnesses/codex.md - ChatGPT: https://gradien.ai/core/docs/harnesses/chatgpt.md Anthropic: - Claude Code Desktop: https://gradien.ai/core/docs/harnesses/claude-code.md - Claude Code CLI: https://gradien.ai/core/docs/harnesses/claude-code.md - Claude web: https://gradien.ai/core/docs/harnesses/claude-web.md - Claude Desktop: https://gradien.ai/core/docs/harnesses/claude-desktop.md Editors and IDE agents: - Cursor: https://gradien.ai/core/docs/harnesses/cursor.md - VS Code / Copilot: https://gradien.ai/core/docs/harnesses/vscode.md - Windsurf / Devin Cascade: https://gradien.ai/core/docs/harnesses/windsurf.md Other agent harnesses: - Hermes: https://gradien.ai/core/docs/harnesses/hermes.md - OpenCode: https://gradien.ai/core/docs/harnesses/opencode.md - Generic MCP clients: https://gradien.ai/core/docs/harnesses/generic.md 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 - 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 Core should mostly disappear after setup. Keep asking for normal work. A connected agent can use Core automatically when visible context, prior decisions, files, tasks, or saved private outcomes would help. Good user prompts after setup are just normal work prompts: - Update the landing page copy. - Find what we decided about pricing. - Continue the onboarding work from last time. - Review this PR against our product direction. The Core loop is meant to happen in the background: 1. Use `core_start_work` when current visible Core context would improve the work. 2. Use `core_search` and `core_read` to pull exact visible context. 3. Do the work in the current agent or harness. 4. Save ambient artifacts, drafts, and checkpoints to `/private` by default. 5. Use `/teams/` 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 I start? Use the setup page at https://gradien.ai/core/docs. If you want an agent to help with setup, paste this message into the app you are connecting: ```text Please help me set up Core for this agent. Core is a home base for AI agents: it keeps memory, files, decisions, tasks, and work context synced across tools, harnesses, and models. Use this official setup reference: https://gradien.ai/core/docs/reference ``` The setup reference includes the setup CLI command and agent-specific connection paths. --- ## Codex Setup Source: https://gradien.ai/core/docs/harnesses/codex.md # Codex Setup Official source: https://developers.openai.com/codex/mcp Codex supports remote MCP servers. Core can be registered as a remote MCP server and authenticated through Codex's OAuth flow. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Recommended Setup Run the guided installer: ```bash npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness codex ``` The installer creates a short-lived Core signup/login session and registers Core with Codex. ## Manual Setup If you prefer to run the Codex commands yourself: ```bash codex mcp add core --url https://core.gradien.ai/mcp codex mcp login core ``` After browser login, a URL like `http://127.0.0.1:/callback/...` is normal. That is the one-time local callback where Codex receives the OAuth code. The MCP server itself remains remote at `https://core.gradien.ai/mcp`. ## Important Codex Notes - Do not add `--oauth-resource` for Core. Codex discovers the OAuth resource from Core protected-resource metadata, and adding it manually can duplicate the `resource` parameter. - Do not narrow OAuth to `--scopes profile,email`. Core may require the server-advertised scopes to select the correct workspace. - Do not extract or copy tokens from Codex auth/cache files. Codex owns those OAuth credentials. - Older Codex builds have had fragile OAuth behavior. If Codex reports an experimental OAuth flag requirement or fails while parsing metadata, update Codex and retry. ## Verify Check the saved MCP entry: ```bash codex mcp get core codex mcp list ``` Current Codex CLI versions may not expose a direct `tools/list` command. After setup and login, restart Codex or open a fresh Codex session so the Core tools can load. If a fresh session still reports `AuthRequired`, run: ```bash codex mcp logout core codex mcp login core ``` Then restart Codex again. If native OAuth still fails on a current Codex version, use the Core local bridge fallback only after a safe scoped Core credential is available. --- ## Claude Code Setup Source: https://gradien.ai/core/docs/harnesses/claude-code.md # Claude Code Setup Official source: https://docs.anthropic.com/en/docs/claude-code/mcp Claude Code can add remote MCP servers from the command line and complete OAuth through the app's MCP UI. Claude Code is different from Claude Desktop. Use this page only for Claude Code. ## Recommended Setup Run the guided installer: ```bash npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness claude-code ``` The installer creates a short-lived Core signup/login session, registers Core for Claude Code, and prints any agent-specific next steps. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Authentication Claude Code may not show a newly added MCP server inside `/mcp` until the app restarts. Use this order: 1. Finish the installer. 2. Fully quit and reopen Claude Code, or start a fresh Claude Code session. 3. Run `/mcp`. 4. Select Core. 5. Choose Authenticate or Connect if prompted. 6. Approve Core in the browser. If Core is missing from `/mcp` before a restart, treat that as a stale Claude Code session rather than a failed install. ## Verify After authentication, Core should appear as a connected MCP server and expose Core tools in a fresh Claude Code session. If tools are still missing, restart Claude Code once more before reinstalling. --- ## Claude Web Setup Source: https://gradien.ai/core/docs/harnesses/claude-web.md # Claude Web Setup Official source: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp Claude web connects to Core through a custom connector in Claude settings. Claude's cloud service must be able to reach the MCP server over public HTTPS. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Setup 1. Open Claude in your browser. 2. Open Settings or Customize. 3. Go to Connectors. 4. Choose Add custom connector. 5. Enter name: `Core`. 6. Paste `https://core.gradien.ai/mcp`. 7. Approve the Core login or permissions screen. 8. Start a fresh Claude chat if the connector does not appear in the current chat. For Team or Enterprise plans, an Owner may need to add the connector under Organization settings first. Members can then connect Core individually from their own Claude connector settings. ## Optional CLI Signup The Core setup CLI can create or link your Core account before you add the connector: ```bash npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness claude-web ``` This CLI step is optional for Claude web. The key setting in Claude is still the remote MCP URL above. ## Troubleshooting If Claude shows `Authorization with the MCP server failed`, check the Core troubleshooting page. Common causes include OAuth metadata, dynamic client registration, redirect URI allowlists, token scopes, or token audience/resource mismatch. --- ## Claude Desktop Setup Source: https://gradien.ai/core/docs/harnesses/claude-desktop.md # Claude Desktop Setup Official source: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp Claude Desktop may support Core through remote custom connectors or through a desktop extension package, depending on the current Claude plan and app version. Claude Desktop is different from Claude Code. Do not use `claude mcp add` or Claude Code config commands for Claude Desktop. ## Remote Connector If Claude Desktop offers custom connectors: 1. Open Claude Desktop. 2. Open Settings. 3. Go to Connectors. 4. Choose Add custom connector. 5. Name the connector `Core`. 6. Paste this URL: ```text https://core.gradien.ai/mcp ``` 7. Approve the Core login or permissions screen. 8. Restart Claude Desktop if the tools do not appear. ## Desktop Extension If your Core account provides a Claude Desktop extension: 1. Download the Core desktop extension from Core. 2. Open Claude Desktop. 3. Open Settings. 4. Go to Extensions. 5. Install the downloaded Core extension. 6. Paste a Core connector key only if Claude Desktop asks for it. 7. Restart Claude Desktop. ## Verify Open a fresh Claude Desktop chat after setup. Core tools should appear in the available connector/tool list once the connector is loaded and authenticated. --- ## ChatGPT Setup Source: https://gradien.ai/core/docs/harnesses/chatgpt.md # ChatGPT Setup Official source: https://developers.openai.com/apps-sdk/build/auth ChatGPT connects to Core through a remote MCP connector. This is configured in ChatGPT settings, not by editing local files. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Setup 1. Open ChatGPT. 2. Open Settings. 3. Go to Apps, Connectors, or Developer Mode, depending on the current ChatGPT UI. 4. Add a custom app, custom connector, or remote MCP connector. 5. Choose Server URL, not Tunnel. 6. Paste `https://core.gradien.ai/mcp`. 7. Choose OAuth for authentication. 8. Approve Core when ChatGPT opens the login or consent screen. Use Tunnel only for a private/local MCP server such as `localhost`, a dev machine, or a server hidden behind a firewall. Hosted Core uses the public HTTPS Server URL path. ## If Connection Fails ChatGPT may show a generic error if the OAuth handshake fails. The most common causes are: - OAuth scopes requested by ChatGPT are not allowed by the provider. - The ChatGPT redirect URI is not accepted by the authorization server. - Dynamic Client Registration or the equivalent client registration path is not available. - The issued access token is rejected by the Core MCP server because the token audience, resource, issuer, expiry, or organization claims do not match. For production Core, do not switch to No Authentication. Core contains user memory and should be protected by OAuth. No Authentication is only appropriate for a separate disposable smoke-test server. ## Verify After ChatGPT says the connector is connected, start a fresh chat and check whether Core tools are available. ChatGPT may expose compatibility tools such as search/fetch as well as standard Core MCP tools, depending on current ChatGPT connector support. --- ## Cursor Setup Source: https://gradien.ai/core/docs/harnesses/cursor.md # Cursor Setup Official source: https://cursor.com/docs/mcp.md Cursor supports remote MCP servers through Cursor settings and `mcp.json`. Core should usually be configured globally so it follows you across projects. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` Global config path: ```text ~/.cursor/mcp.json ``` Project config path: ```text .cursor/mcp.json ``` ## Recommended Setup Run the guided installer: ```bash npx -y @gradien/core-agent-setup ``` The installer creates a Core signup/login session, backs up existing Cursor MCP config, and adds Core where Cursor can load it. ## Manual Config The expected global config shape is: ```json { "mcpServers": { "core": { "url": "https://core.gradien.ai/mcp" } } } ``` If the file already contains other MCP servers, preserve them and add only the `core` entry. Do not put bearer tokens or connector keys in Cursor config unless OAuth is impossible and you intentionally choose that fallback. ## Load and Authenticate Cursor may not hot-load new MCP servers in an existing chat. 1. Reload Cursor with `Cmd+Shift+P` -> `Developer: Reload Window`, or fully quit and relaunch Cursor. 2. Open Cursor Settings. 3. Go to Features -> Model Context Protocol. 4. Find Core. It may appear as `core` or `user-core`. 5. Click Connect or Authenticate. 6. Approve Core in the browser. If only an `mcp_auth` tool is visible, Core is present but not authenticated yet. Complete the OAuth step from Cursor settings or by using the visible auth tool. ## If Cursor Hangs During OAuth If Cursor stays on `Waiting for callback...` or `Exchanging token...` after the browser returned to Cursor: 1. Stop clicking Connect/Allow repeatedly. 2. Fully quit and relaunch Cursor. 3. Try Connect once more. 4. Check Cursor MCP Logs in the Output panel: `Cmd+Shift+U` -> `MCP Logs`. Repeated unauthenticated requests to `/mcp` mean Cursor can reach Core but did not complete or store OAuth. That is usually an OAuth callback state issue, not a bad URL. ## Fallback If OAuth keeps hanging after one clean relaunch, a scoped Core connector key can be used as a fallback. Store it as locally and narrowly as possible, prefer environment-variable interpolation if Cursor supports it, and rotate the key later. --- ## VS Code Setup Source: https://gradien.ai/core/docs/harnesses/vscode.md # VS Code Setup 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 copy Cursor's `mcp.json` format into VS Code unless the current VS Code docs explicitly say to do so. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Setup 1. Open the current VS Code MCP server documentation. 2. Open the user or workspace MCP configuration location documented by VS Code. 3. Back up the existing config before editing it. 4. Add Core using the current VS Code `servers` shape for remote MCP servers. 5. Use `https://core.gradien.ai/mcp` as the server URL. 6. Save the config. 7. Approve or start the server if VS Code prompts. ## Verify Open a fresh VS Code/Copilot chat or reload the VS Code window. Core should appear in the MCP server/tool list after VS Code loads the config and completes authentication. --- ## Windsurf Setup Source: https://gradien.ai/core/docs/harnesses/windsurf.md # Windsurf Setup Official source: https://docs.windsurf.com/windsurf/cascade/mcp Windsurf/Cascade has its own MCP configuration conventions. Some flows use `serverUrl` for remote MCP servers. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Setup 1. Open the current Windsurf MCP documentation. 2. Open Windsurf's MCP settings or local MCP config location. 3. Back up any existing config before editing it. 4. Add Core using the current Windsurf remote MCP shape. 5. Use `https://core.gradien.ai/mcp` as the server URL. 6. Save the config and reload Windsurf if needed. 7. Approve OAuth if Windsurf prompts for browser authentication. ## Verify Core should appear in Windsurf/Cascade's MCP server list after reload. If tools do not appear, check for enterprise/admin controls, MCP enablement settings, or tool-count limits in the current Windsurf version. --- ## Hermes Setup Source: https://gradien.ai/core/docs/harnesses/hermes.md # Hermes Setup 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 usually discovers MCP tools when a new Hermes session starts. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Recommended Setup Run the guided installer: ```bash npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness hermes ``` The direct Hermes command is: ```bash hermes mcp add core --url https://core.gradien.ai/mcp --auth oauth ``` Prefer the guided installer first because it handles Core signup/login before registration. ## Load and Verify 1. Restart Hermes or start a fresh Hermes session after registration. 2. Check the MCP server list: ```bash hermes mcp list ``` 3. Test the Core server if your Hermes version supports it: ```bash hermes mcp test core ``` 4. If Hermes prompts for OAuth, approve Core in the browser. Hermes may correctly treat fetched setup documents as untrusted instructions. That is fine. Core setup does not change Hermes identity, policies, SOUL.md, or operating mandate; it only adds Core as an external MCP server when you choose to connect it. --- ## OpenCode Setup Source: https://gradien.ai/core/docs/harnesses/opencode.md # OpenCode Setup Official source: https://opencode.ai/docs/mcp-servers/ OpenCode supports remote MCP server configuration and OAuth. It can prompt for OAuth automatically when the server is first used. Core MCP server URL: ```text https://core.gradien.ai/mcp ``` ## Recommended Setup Run the guided installer: ```bash npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness opencode ``` Prefer remote MCP plus OAuth. Do not paste long-lived connector keys into OpenCode config unless OAuth is impossible and you intentionally choose that fallback. ## Verify Check the configured MCP servers: ```bash opencode mcp list ``` If Core is unauthenticated, stale, or unable to load tools, start the OAuth flow: ```bash opencode mcp auth core ``` If `opencode mcp auth core` says Core already has valid credentials, do not re-authenticate unless you intentionally want to replace those credentials. Continue with: ```bash opencode mcp debug core ``` If OpenCode still reports `needs_auth` after valid credentials, use one clean reset: ```bash opencode mcp logout core opencode mcp auth core ``` Then restart OpenCode or start a fresh OpenCode session. --- ## Generic MCP Setup Source: https://gradien.ai/core/docs/harnesses/generic.md # Generic MCP Setup Use this page for any MCP client that is not listed elsewhere. Core MCP endpoint: ```text https://core.gradien.ai/mcp ``` OAuth protected resource metadata: ```text https://core.gradien.ai/.well-known/oauth-protected-resource/mcp ``` ## Preferred Setup 1. Add Core as a remote Streamable HTTP MCP server. 2. Use `https://core.gradien.ai/mcp` as the server URL. 3. Let the client discover OAuth from Core protected-resource metadata. 4. Complete browser consent. 5. Verify `initialize` and `tools/list`. ## Fallback Use a scoped Core connector key only if the client cannot complete OAuth. Connector keys should be personal, scoped, revocable, and stored locally. Avoid adding long-lived keys to shared project files. --- ## Troubleshooting Source: https://gradien.ai/core/docs/troubleshooting.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. - Restart or reload the app if that harness discovers MCP servers only at startup. - Reopen the current agent-specific guide and compare the saved config shape. ## Tools are missing - Call `tools/list` if the harness exposes diagnostics. - Confirm the endpoint is Core MCP, not the website root. - Confirm the user completed OAuth or the bearer key is present. - For local harnesses, explain that `localhost` or `127.0.0.1` OAuth callback URLs are expected and are not the MCP server location. ## OAuth failed - Fetch the protected resource metadata. - Confirm the authorization server is present. - Confirm the client requested Core-advertised `scopes_supported`; for Core this includes OpenID sign-in identity plus workspace/org selection consent where the authorization server supports it. - For Claude web, remember Claude connects from Anthropic cloud infrastructure. The MCP server must be publicly reachable from Anthropic, not just from the user's device. - For Claude web, if the UI shows `Authorization with the MCP server failed` with an `ofid_...` reference, treat that reference as a support/correlation id that may be Anthropic-side unless it appears in Core logs. Do not assume it is a Core log id. - For Claude web, confirm the auth server supports Dynamic Client Registration or that the user entered configured OAuth Client ID/Secret in Claude Advanced settings. Also confirm Claude's redirect URI is accepted by the OAuth provider. - For ChatGPT web, confirm the auth server supports one ChatGPT client registration path: Client ID Metadata Documents, Dynamic Client Registration, or predefined OAuth client credentials. Also confirm the ChatGPT callback URL is allowlisted. - For Cursor, an unauthenticated Core server may expose only `mcp_auth`. Use that tool or Cursor Settings -> Features -> Model Context Protocol -> Connect/Authenticate to finish OAuth. - If a Codex build says OAuth requires an experimental flag or fails parsing metadata, update Codex instead of enabling experimental OAuth flags. - For OpenCode, do not run `opencode mcp auth ` just because it was printed as an available command. Run it only when OpenCode reports missing/stale auth. - Retry browser consent once after checking the metadata and app state. - Fall back to a scoped connector key only if the harness cannot complete OAuth. ## Claude Code failed - If setup registered Core but `/mcp` does not show Core, do not assume auth failed. Claude Code may not load newly added MCP servers into the current session. - Fully quit/relaunch Claude Code or start a fresh Claude Code session, then run `/mcp` again. - Authenticate only after Core appears in `/mcp`. - If `/mcp` shows Core but says it needs authentication, select Core and approve browser login. If browser auth completes but Core remains unauthenticated, restart Claude Code once and check `/mcp` again. ## Claude web failed - Confirm the user pasted the exact remote MCP server URL: `https://core.gradien.ai/mcp`. - Confirm the user chose Add custom connector. For Team or Enterprise plans, an Owner may need to add it in Organization settings before members can connect. - Fetch `/.well-known/oauth-protected-resource/mcp`; it must be valid JSON and include `authorization_servers`. - Fetch the authorization server metadata; it must include authorization and token endpoints, PKCE S256 support, and Dynamic Client Registration or a configured Claude OAuth client. - If Claude gives an `ofid_...` reference, search Core/Fly logs for it, but if no match exists, treat it as Anthropic-side and continue with metadata, DCR/client credentials, redirect URI, scope, and audience checks. - If no Core logs show `/mcp` discovery or auth challenge traffic after this PR is deployed, suspect network reachability from Anthropic cloud or a failure before Claude reached Core. ## Cursor failed - Confirm `~/.cursor/mcp.json` contains `"core": { "url": "https://core.gradien.ai/mcp" }` under `mcpServers`, while preserving any other servers. - Reload Cursor with Cmd+Shift+P -> Developer: Reload Window, or open a new Cursor window. - If Core appears as `user-core`, unauthenticated, or with only `mcp_auth`, finish OAuth by running `mcp_auth` from chat or clicking Connect/Authenticate in Cursor Settings -> Features -> Model Context Protocol. - If Cursor stays on `Waiting for callback...` or `Exchanging token...` after the user clicks Allow and opens Cursor, do not keep clicking Connect or Allow. Fully quit/relaunch Cursor once, then check Cursor MCP Logs. - If Fly/Core logs show repeated unauthenticated `/mcp` requests with a `Cursor/` 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 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 /mcp`. - Do not retry with `--scopes profile,email`; let Codex use Core metadata. If a stale token was minted before metadata changed, run `codex mcp logout core`, then `codex mcp login core`. - If Codex says remote OAuth requires an experimental setting, or OAuth metadata parsing fails on an old build, check `codex --version` and update Codex. Do not persist experimental OAuth flags as part of setup. - If `codex mcp login core` reports success but a new Codex runtime still gets AuthRequired during tool discovery, update/restart Codex and retry once. Avoid repeated nested `codex exec` probes. - Prefer the Core local bridge path only after native OAuth fails with a clean config, clean login, fresh Codex session, and current Codex version. - Verify the bridge can call Core `tools/list` when using the bridge fallback. ## ChatGPT web failed - Use Server URL, not Tunnel, for hosted Core: `https://core.gradien.ai/mcp`. - Use OAuth for production Core. Do not use No Authentication against user memory except on a separate disposable smoke-test server. - Fetch `/.well-known/oauth-protected-resource/mcp` and confirm `authorization_servers` is present. - Fetch the authorization server metadata and confirm it has authorization and token endpoints, PKCE S256 support, and either Client ID Metadata Documents, Dynamic Client Registration, or a predefined OAuth client configured in ChatGPT. - Confirm the ChatGPT redirect URL shown in app settings, usually `https://chatgpt.com/connector/oauth/{callback_id}`, is allowlisted by the OAuth provider. - If ChatGPT redirects back with `error=invalid_scope` and says the OAuth client is not allowed to request `openid`, confirm Core protected-resource metadata advertises `openid` in `scopes_supported`, then delete/recreate the draft ChatGPT app or re-register OAuth so ChatGPT gets a new client allowed to request the updated scopes. - If ChatGPT shows only “There was a problem connecting Core. Try again later,” treat it as likely OAuth registration/redirect/provider metadata failure until proven otherwise. ## Wrong workspace - Confirm which Core workspace should be connected. - Sign into the correct workspace in the browser. - Do not reuse a connector key from another workspace. If stuck, fetch the full context at https://gradien.ai/core/llms-full.txt and report the exact harness, command/config used, error text, and whether OAuth or bearer auth was attempted.