MCP Integration

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:

Navigate to your collection
Click the “Connect” button
Select the “MCP” tab
Choose your AI client (Cursor, VS Code, Claude Desktop, etc.)
Generate an API key automatically
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

Get your API key from zeroset.com → Settings → API Keys, or generate one automatically through the collection’s Connect dialog.

Cursor
VS Code
Windsurf
Claude Desktop
Claude Code

Cursor supports HTTP-based MCP servers with native transport.Configuration File: .cursor/mcp.json

{
  "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

VS Code with Copilot or Cline supports HTTP-based MCP servers.Configuration File: .vscode/mcp.json

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

VS Code uses "servers" as the top-level key, not "mcpServers".

View VS Code MCP docs

Windsurf supports HTTP-based MCP servers through its Cascade feature.Configuration File: ~/.codeium/windsurf/mcp_config.json

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

Windsurf uses "serverUrl" instead of "url".

View Windsurf MCP docs

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

{
  "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"
      }
    }
  }
}

The mcp-remote package bridges HTTP MCP servers to stdio transport automatically.

View Claude Desktop MCP docs

Claude Code supports HTTP transport directly.Quick Install (CLI):

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

{
  "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

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 → 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. 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:

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):

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

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

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.

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

​Quick Setup

​Configuration

​Available Tools

​add_memory

​search_memories

​Troubleshooting

​Web-Hosted vs Local Installation

​Web-Hosted (Recommended)

​Local Installation (Optional)

Quick Setup

Configuration

Available Tools

`add_memory`

`search_memories`

Troubleshooting

Web-Hosted vs Local Installation

Web-Hosted (Recommended)

Local Installation (Optional)