# MCP setup (Claude, ChatGPT, Cursor, Windsurf, Codex)

Source: https://www.gryz.ai/docs/mcp/setup/
Updated: 2026-11-18

## What it does [#what-it-does]

The Gryz MCP server lets your AI assistant use shared memory, manage documents, and keep private Notes in your account. Every tool is free with any signed-in account, with no subscription required.

## Requirements [#requirements]

* A free Gryz account
* MCP server URL (always use `www`, because apex redirects drop auth headers)

**Primary URL (use this for new setups):**

```text
https://www.gryz.ai/api/mcp
```

<Note>
  The previous MCP URL `https://www.grtwo.app/api/mcp/` still works if your assistant is already configured with it. New connections should use the Gryz URL above.
</Note>

## Connect in Claude.ai [#connect-in-claudeai]

1. Open **Customize**, then **Connectors** in Claude
2. Select **+ Add**, then **Add custom connector**
3. Paste `https://www.gryz.ai/api/mcp`
4. Complete OAuth sign-in when prompted. Your browser opens to authorize access
5. Ask Claude to list or publish documents (see example prompts below)

## Connect in ChatGPT [#connect-in-chatgpt]

Gryz is listed in ChatGPT, so any ChatGPT plan can add it. Sign in with your Gryz account. No API key is needed.

1. Open [Gryz in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6acd840c118c81919b71f8a5783f8c96) and select **Install plugin**
2. Sign in to Gryz when ChatGPT asks
3. Start a new chat, type &#x2A;*@** and pick **Gryz**

* ChatGPT can take up to 30 seconds to show the Connect dialog. That is normal.
* At work, your ChatGPT admin may need to allow Gryz first.

**Add it by address instead.** If you'd rather add Gryz yourself:

1. In ChatGPT, open **Plugins*&#x2A;, select &#x2A;*+**, then **Add custom MCP server**
2. Name it **Gryz**, paste `https://www.gryz.ai/api/mcp`, and choose **OAuth** to sign in
3. Select **Create**, install it, then sign in to Gryz when ChatGPT asks

Don't see **Plugins**? Open **Settings**, then **Connectors**, then **Advanced**, and turn on **Developer mode**.

Using Codex? See [Connect in Codex](#connect-in-codex) below.

## Connect in Grok [#connect-in-grok]

Add Gryz as a custom connector on the web and sign in with your Gryz account. No API key is needed.

1. Open [grok.com/connectors](https://grok.com/connectors) and select **New Connector**, then **Custom**
2. Paste `https://www.gryz.ai/api/mcp` and sign in to Gryz
3. Start a new chat and ask Grok to check its Gryz connection

On Grok Business, your admin adds Gryz in the xAI console under **Connectors**.

## Connect in Cursor [#connect-in-cursor]

Add the server to `~/.cursor/mcp.json`. OAuth is recommended because no API key sits in the file.

After connecting, use the [MCP tools reference](/docs/mcp/tools/) to verify the available document and Notes operations.

<McpCursorInstall />

**Option A: OAuth (recommended)**

```json
{
  "mcpServers": {
    "gryz": {
      "url": "https://www.gryz.ai/api/mcp"
    }
  }
}
```

**Option B: API key**

Generate a key on the [API keys page](https://www.gryz.ai/account/api-keys/), then add it as a Bearer token:

```json
{
  "mcpServers": {
    "gryz": {
      "url": "https://www.gryz.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer gryz_YOUR_KEY_HERE"
      }
    }
  }
}
```

## Connect in Windsurf [#connect-in-windsurf]

Gryz is in the Windsurf (Cascade) plugin marketplace. Open **Customize → Browse marketplace** and search **Gryz**, or use the one-click install link:

```text
windsurf://windsurf-mcp-registry?serverName=gryz
```

Click **Install**, then complete OAuth sign-in when Cascade prompts. The link opens the marketplace page only when your team has MCP access enabled.

## Connect in Codex [#connect-in-codex]

Add a streamable HTTP server with the Codex CLI. The same `~/.codex/config.toml` entry is used by the Codex app and IDE extension. OAuth is recommended because no API key sits in the file.

**Option A: OAuth (recommended)**

```bash
codex mcp add gryz --url https://www.gryz.ai/api/mcp
codex mcp login gryz
```

```toml
[mcp_servers.gryz]
url = "https://www.gryz.ai/api/mcp"
```

**Option B: API key**

Generate a key on the [API keys page](https://www.gryz.ai/account/api-keys/), then point Codex at the environment variable that holds it:

```bash
export GRYZ_API_KEY=gryz_YOUR_KEY_HERE
codex mcp add gryz --url https://www.gryz.ai/api/mcp --bearer-token-env-var GRYZ_API_KEY
```

Start a new Codex session after adding the server, then run `/mcp` to confirm Gryz tools.

## Example prompts [#example-prompts]

* `Publish this markdown to Gryz as a public doc titled "Q3 Roadmap"`
* `Save this HTML to my Gryz dashboard as a private document`
* `List my Gryz documents`
* `Get my Gryz document with slug "q3-roadmap"`
* `Delete my Gryz test document with slug "draft-notes"`
* `Go through the comments on my Gryz doc "q3-roadmap" with me`

## Tools [#tools]

<McpToolsTable />

See the [MCP tools reference](/docs/mcp/tools/) for required inputs, mutation semantics, and per-plan hourly limits. For private working context, read the [Notes overview](/docs/notes/overview/).

## Troubleshooting [#troubleshooting]

* **Unknown client:** Claude registers a fresh `client_id` via `/api/oauth/register/` before opening the browser. Remove the connector in Claude, add `https://www.gryz.ai/api/mcp` again, and complete sign-in in the *same browser* Claude opens.
* **Sign-in link on a different device**: OAuth state lives in a short-lived browser cookie. Start the connection on desktop and open the email link on desktop, not on your phone. Typing the email code in the same browser tab avoids this.
* **After the sign-in link or code**: you should land on the Allow screen automatically. If you briefly see "Finishing sign-in…", wait a second; do not refresh manually.
* **Use www, no trailing slash:** Always add `https://www.gryz.ai/api/mcp`. The apex domain redirects and strips auth headers. The server answers the path with or without a trailing slash, but the OAuth resource identifier has none, so Cursor and Codex expect the slash-less form.
* **Claude Desktop:** Add the connector under Customize → Connectors (not `claude_desktop_config.json`). Claude uses `https://claude.ai/api/mcp/auth_callback` as the redirect URI.
* **No comment tools** (`list_comment_threads`, `respond_to_comments`): apps connected before comment tools existed don't have permission for them. Disconnect Gryz in your AI app, connect it again, and press **Allow** on the screen that lists reading and posting comments. If your app reads comments but says it can't answer them, restart it: some apps keep an old tool list until they restart. If the app can also see a company in Gryz, comments may stay off in that app, or posting and acting on them may work only on your own private documents. See [Comments and AI agents](/docs/comments/agents/#reconnect-your-ai-app-once-to-get-the-comment-tools).
* **Codex OAuth resource mismatch:** Re-add with `--oauth-resource https://www.gryz.ai/api/mcp` and run `codex mcp login gryz` again. Start a new Codex session before expecting tools.

## Related reading [#related-reading]

* [Shared context for AI agents](/topics/shared-context/)
* [Search your documents from any assistant](/topics/document-search/)
* [How do I share context between Claude Code and Cursor?](/gryzle/share-context-between-claude-code-and-cursor/)
* [Shared context for AI coding agents, over MCP](/gryzle/shared-context-for-ai-coding-agents/)
