> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ceramic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search MCP

> Connect AI agents to Ceramic Search via MCP

The Ceramic MCP Server enables AI systems to search the web through the [Model Context Protocol](https://modelcontextprotocol.io/).

## Setup

<Tabs>
  <Tab title="Cursor">
    <Card title="Install in Cursor" icon="link" href="cursor://anysphere.cursor-deeplink/mcp/install?name=ceramic&config=eyJ1cmwiOiJodHRwczovL21jcC5jZXJhbWljLmFpL21jcCJ9" horizontal>
      Click to install the Ceramic MCP server directly in Cursor.
    </Card>

    Or add manually to your \~/.cursor/mcp.json:

    ```json theme={null}
    {
      "mcpServers": {
        "ceramic": {
          "url": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    <Card title="Install in VS Code" icon="link" href="https://insiders.vscode.dev/redirect/mcp/install?name=ceramic&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ceramic.ai%2Fmcp%22%7D" horizontal>
      Click to install the Ceramic MCP server directly in VS Code.
    </Card>

    Or add manually to your .vscode/mcp.json:

    ```json theme={null}
    {
      "servers": {
        "ceramic": {
          "type": "http",
          "url": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    1. Register the Ceramic plugin marketplace:

    ```bash theme={null}
    claude plugin marketplace add CeramicTeam/ceramic-claude-code-plugins
    ```

    2. Install the plugin:

    ```bash theme={null}
    claude plugin install ceramic-search@ceramic-ai
    ```

    Or within a session: `/plugin install ceramic-search@ceramic-ai`

    3. Start a new Claude Code session. You'll be prompted to authenticate via WorkOS OAuth — a browser window opens automatically.
  </Tab>

  <Tab title="Claude Desktop">
    <Tabs>
      <Tab title="Paid Plan (Pro / Team / Enterprise)">
        Connect directly from the **Claude desktop** app or **claude.ai**:

        1. Go to **Settings → Connectors**
        2. Click **Add Custom Connector**
        3. Enter a name (e.g. `ceramic`)
        4. Paste the MCP server URL: `https://mcp.ceramic.ai/mcp`
        5. Click **Add**
      </Tab>

      <Tab title="Free Plan">
        Add to your Claude Desktop config file. Requires Node.js to be installed.

        * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

        ```json theme={null} theme={null}
          {
            "mcpServers": {
              "ceramic": {
                "command": "npx",
                "args": [
                  "-y",
                  "mcp-remote",
                  "https://mcp.ceramic.ai/mcp"
                ]
              }
            }
          }
        ```

        Restart Claude Desktop after saving the config.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Codex CLI">
    1. Register the Ceramic plugin marketplace:

    ```bash theme={null}
    codex plugin marketplace add CeramicTeam/ceramic-codex-plugins
    ```

    2. Install the plugin:

    Inside a Codex session, run `/plugins`, find `ceramic-search` under Ceramic AI Plugins, and select install. Codex opens a WorkOS OAuth page automatically.

    If the browser doesn't open automatically, run this from a terminal outside Codex:

    ```bash theme={null}
    codex mcp login ceramic-search
    ```

    3. Begin a new Codex session. The `ceramic-search` skill is active in every session and invokes automatically whenever the agent needs current web information.

    **Note:** If your OAuth session expires, re-run the login command to re-authenticate.
  </Tab>
</Tabs>

Setup for additional clients can be found below.

<AccordionGroup>
  <Accordion title="ChatGPT">
    **Note:** MCP server support requires a **ChatGPT Plus, Pro, or Team** plan.

    From the ChatGPT desktop app or web browser:

    1. Go to **Settings → Apps**
    2. Click **Advanced Settings**
    3. Enable **Developer Mode**
    4. Click **Create App**
    5. Paste the MCP server URL: `https://mcp.ceramic.ai/mcp`
    6. Click **Add**
  </Accordion>

  <Accordion title="Gemini CLI">
    Add to your `~/.gemini/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ceramic": {
          "httpUrl": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Google Antigravity">
    1. In the Agent panel on the right side, click the three-dot menu
    2. Select MCP Servers
    3. Select **Manage MCP Servers**
    4. Click **View Raw config**
    5. Add the following:

    ```json theme={null}
    {
      "mcpServers": {
        "ceramic": {
          "serverUrl": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Kiro">
    Add to your `~/.kiro/settings/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ceramic": {
          "url": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="OpenCode">
    Add to your `opencode.json`:

    ```json theme={null}
    {
      "mcp": {
        "ceramic": {
          "type": "remote",
          "url": "https://mcp.ceramic.ai/mcp",
          "enabled": true
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Warp">
    1. Go to **Settings → Agents → MCP Servers**
    2. Click **+Add**
    3. Add the following:

    ```json theme={null}
    {
      "ceramic": {
        "serverUrl": "https://mcp.ceramic.ai/mcp"
      }
    }
    ```
  </Accordion>

  <Accordion title="Windsurf">
    Add to your `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "ceramic": {
          "serverUrl": "https://mcp.ceramic.ai/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Zed">
    Open your Zed settings (**Zed → Settings → Open Settings JSON**) and add:

    ```json theme={null}
    {
      "context_servers": {
        "ceramic": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.ceramic.ai/mcp"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Available Tools

### `ceramic_search`

Searches the web and returns a ranked list of results. Agents get better results with specific terms than with conversational phrasing. See [search best practices](/api/search/best-practices) for more guidance.