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

> [tab] Cursor
>
> > [card] [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=ceramic\&config=eyJ1cmwiOiJodHRwczovL21jcC5jZXJhbWljLmFpL21jcCJ9)
> >
> > Click to install the Ceramic MCP server directly in Cursor.
>
> Or add manually to your \~/.cursor/mcp.json:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ceramic": {
>       "url": "https://mcp.ceramic.ai/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> > [card] [Install in VS Code](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)
> >
> > Click to install the Ceramic MCP server directly in VS Code.
>
> Or add manually to your .vscode/mcp.json:
>
> ```json theme={null}
> {
>   "servers": {
>     "ceramic": {
>       "type": "http",
>       "url": "https://mcp.ceramic.ai/mcp"
>     }
>   }
> }
> ```

> [tab] Claude Code
>
> 1. Register the Ceramic plugin marketplace:
>
> ```bash theme={null}
> claude plugin marketplace add CeramicTeam/agent-skills
> ```
>
> 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.
>
> The plugin includes the `ceramic-search` skill, so you don't need to install the [agent skill](https://docs.ceramic.ai/api/search/agent-skill.md) separately.
>
> **Note:** If you installed the plugin from `CeramicTeam/ceramic-claude-code-plugins`, run step 1, then `claude plugin update ceramic-search@ceramic-ai` and restart Claude Code.

> [tab] Claude Desktop
>
> > [tab] 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] 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] Codex CLI
>
> 1. Register the Ceramic plugin marketplace:
>
> ```bash theme={null}
> codex plugin marketplace add CeramicTeam/agent-skills
> ```
>
> 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. You don't need to install the [agent skill](https://docs.ceramic.ai/api/search/agent-skill.md) separately.
>
> **Note:** If your OAuth session expires, re-run the login command to re-authenticate.
>
> **Note:** If you installed the plugin from `CeramicTeam/ceramic-codex-plugins`, remove that marketplace before step 1 with `codex plugin marketplace remove ceramic-ai`. Your installed plugin updates the next time you start Codex.

Setup for additional clients can be found below.

> [accordion] 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] Gemini CLI
>
> Add to your `~/.gemini/settings.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ceramic": {
>       "httpUrl": "https://mcp.ceramic.ai/mcp"
>     }
>   }
> }
> ```

> [accordion] 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] Hermes Agent
>
> Add to your `~/.hermes/config.yaml`:
>
> ```yaml theme={null}
> mcp_servers:
>   ceramic:
>     url: "https://mcp.ceramic.ai/mcp"
>     headers:
>       Authorization: "Bearer YOUR_API_KEY"
> ```

> [accordion] Kiro
>
> Add to your `~/.kiro/settings/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ceramic": {
>       "url": "https://mcp.ceramic.ai/mcp"
>     }
>   }
> }
> ```

> [accordion] OpenCode
>
> Add to your `opencode.json`:
>
> ```json theme={null}
> {
>   "mcp": {
>     "ceramic": {
>       "type": "remote",
>       "url": "https://mcp.ceramic.ai/mcp",
>       "enabled": true
>     }
>   }
> }
> ```

> [accordion] 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] Windsurf
>
> Add to your `~/.codeium/windsurf/mcp_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ceramic": {
>       "serverUrl": "https://mcp.ceramic.ai/mcp"
>     }
>   }
> }
> ```

> [accordion] 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"]
>     }
>   }
> }
> ```

## 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](https://docs.ceramic.ai/api/search/best-practices.md) for more guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.