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

# MCP Integration

> Connect AI assistants to Nebula via Model Context Protocol

Connect Claude Desktop, Cursor, VS Code, and other MCP-compatible clients to Nebula. Your AI assistant can store and search memories directly using our web-hosted MCP server.

Nebula's hosted MCP service is inbound: Nebula exposes MCP tools to MCP clients. It is not a connector that lets Nebula call arbitrary external MCP servers.

## Quick Setup

The easiest way to connect is through your collection's Connect dialog at [zeroset.com](https://zeroset.com):

1. Navigate to your collection
2. Click the "Connect" button
3. Select the "MCP" tab
4. Choose your AI client (Cursor, VS Code, Claude Desktop, etc.)
5. Generate an API key automatically
6. Use the one-click deeplink or copy the configuration

This automatically generates a dedicated API key for your MCP client and provides ready-to-use configuration.

## Configuration

<Info>Get your API key from [zeroset.com](https://zeroset.com) → Settings → API Keys, or generate one automatically through the collection's Connect dialog.</Info>

<Tabs>
  <Tab title="Cursor">
    Cursor supports HTTP-based MCP servers with native transport.

    **Configuration File:** `.cursor/mcp.json`

    ```json theme={null}
    {
      "mcpServers": {
        "nebula-memory": {
          "url": "https://mcp.zeroset.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "X-Collection-ID": "YOUR_COLLECTION_ID"
          }
        }
      }
    }
    ```

    [View Cursor MCP docs](https://docs.cursor.com/context/mcp)
  </Tab>

  <Tab title="VS Code">
    VS Code with Copilot or Cline supports HTTP-based MCP servers.

    **Configuration File:** `.vscode/mcp.json`

    ```json theme={null}
    {
      "servers": {
        "nebula-memory": {
          "type": "http",
          "url": "https://mcp.zeroset.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "X-Collection-ID": "YOUR_COLLECTION_ID"
          }
        }
      }
    }
    ```

    <Note>VS Code uses `"servers"` as the top-level key, not `"mcpServers"`.</Note>

    [View VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
  </Tab>

  <Tab title="Windsurf">
    Windsurf supports HTTP-based MCP servers through its Cascade feature.

    **Configuration File:** `~/.codeium/windsurf/mcp_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "nebula-memory": {
          "serverUrl": "https://mcp.zeroset.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "X-Collection-ID": "YOUR_COLLECTION_ID"
          }
        }
      }
    }
    ```

    <Note>Windsurf uses `"serverUrl"` instead of `"url"`.</Note>

    [View Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop uses stdio transport and connects to web-hosted servers via the `mcp-remote` bridge package.

    **Configuration File:**

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

    ```json theme={null}
    {
      "mcpServers": {
        "nebula-memory": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.zeroset.com/mcp",
            "--header", "Authorization: Bearer ${NEBULA_API_KEY}",
            "--header", "X-Collection-ID: YOUR_COLLECTION_ID"
          ],
          "env": {
            "NEBULA_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Note>The `mcp-remote` package bridges HTTP MCP servers to stdio transport automatically.</Note>

    [View Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user)
  </Tab>

  <Tab title="Claude Code">
    Claude Code supports HTTP transport directly.

    **Quick Install (CLI):**

    ```bash theme={null}
    claude mcp add --transport http --scope user nebula-memory https://mcp.zeroset.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY" \
      --header "X-Collection-ID: YOUR_COLLECTION_ID"
    ```

    **Manual Configuration:** `~/.claude.json`

    ```json theme={null}
    {
      "mcpServers": {
        "nebula-memory": {
          "transport": "http",
          "url": "https://mcp.zeroset.com/mcp",
          "httpHeaders": {
            "Authorization": "Bearer YOUR_API_KEY",
            "X-Collection-ID": "YOUR_COLLECTION_ID"
          }
        }
      }
    }
    ```

    [View Claude Code MCP docs](https://docs.claude.com/en/docs/claude-code/mcp)
  </Tab>
</Tabs>

## Available Tools

Once connected, your AI assistant gets these memory operations:

### `add_memory`

Store documents or conversation messages.

**Parameters:**

* `content` (required): Text to store
* `role` (optional): For conversations - `user` or `assistant`
* `metadata` (optional): Custom metadata object

**Returns:**

* Shared fields: `success`, `message`, and optional `task_id`
* Document write: `engram_id` and `status`
* Role-based conversation write: `conversation_id` and `message_ids`

**Example:**

```
add_memory(content="User prefers dark mode", metadata={"user_id": "123"})

# Conversation/message write
add_memory(content="Remember this preference", role="user")
```

### `search_memories`

Find and retrieve relevant memories semantically.

**Parameters:**

* `query` (required): Search text
* `effort` (optional): Search effort level - auto/low/medium/high (defaults to auto if omitted)

**Example:**

```
search_memories(query="user preferences")
# Or explicitly set effort:
search_memories(query="user preferences", effort="medium")
```

## Troubleshooting

**Tools not appearing:**

* Restart your AI assistant after config changes
* Verify API key is valid at [zeroset.com](https://zeroset.com) → Settings → API Keys
* Check that the collection ID is correct
* Ensure the configuration file is in the correct location for your client

**Connection errors:**

* Verify your API key has the correct permissions
* Check that the collection ID exists in your account
* Ensure your firewall/proxy allows connections to `mcp.zeroset.com`
* Check the client's console/logs for detailed error messages

**Authentication issues:**

* Make sure the Authorization header includes "Bearer " prefix
* Verify the X-Collection-ID header matches your collection
* Try generating a new API key through the Connect dialog

## Web-Hosted vs Local Installation

### Web-Hosted (Recommended)

All supported clients can connect to Nebula's web-hosted MCP server:

**Direct HTTP Support:**

* **Cursor** - Native HTTP transport
* **VS Code** - Native HTTP transport
* **Windsurf** - Native HTTP transport
* **Claude Code** - Native HTTP transport

**Via mcp-remote Bridge:**

* **Claude Desktop** - Uses `mcp-remote` to bridge HTTP to stdio

**Benefits:**

* No local installation or dependencies required
* Always up-to-date with the latest features
* Simple configuration with just URL and headers
* Automatic API key generation per client
* Works seamlessly across all clients

### Local Installation (Optional)

If you prefer running an MCP server locally, use [`@nebula-ai/mcp-server`](https://github.com/zeroset-inc/nebula-mcp). It is generated from Nebula's public OpenAPI spec by the same in-house pipeline that generates the TypeScript and Python SDKs, so it covers the full Nebula API rather than the curated `add_memory` / `search_memories` tools the hosted server exposes.

Direct invocation:

```bash theme={null}
export NEBULA_API_KEY="your_api_key_here"
npx -y @nebula-ai/mcp-server@latest
```

Example client config (Cursor, Claude Desktop, Claude Code via stdio):

```json theme={null}
{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "@nebula-ai/mcp-server"],
      "env": {
        "NEBULA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

<Note>VS Code uses `servers` instead of `mcpServers`. To run as a remote server, launch with `--transport=http --port=3000` and authenticate with `Authorization: Bearer …`.</Note>

<Info>The local server uses MCP "Code Mode": instead of one tool per endpoint, it exposes a `search_docs` tool and an `execute` tool that runs trusted JavaScript against a pre-authenticated `@nebula-ai/sdk` client. The Worker timeout boundary is not a security sandbox; only expose HTTP mode to trusted callers. Pass the target `collection_id` as an argument inside each `execute` call.</Info>

Use this when you want:

* Full API coverage (every endpoint the generated SDK exposes)
* Local execution / offline development
* A self-hosted MCP under your own auth and network policies