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.

Quick Setup

The easiest way to connect is through your collection’s Connect dialog at trynebula.ai:

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 trynebula.ai → 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.nebulacloud.app/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.nebulacloud.app/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.nebulacloud.app/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.nebulacloud.app/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.nebulacloud.app/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.nebulacloud.app/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

Example:

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

`search_memories`

Find and retrieve relevant memories semantically. Parameters:

query (required): Search text
limit (optional): Maximum results (default: 10)

Example:

search_memories(query="user preferences", limit=5)

Troubleshooting

Tools not appearing:

Restart your AI assistant after config changes
Verify API key is valid at trynebula.ai → 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.nebulacloud.app
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 the MCP server locally or need offline access:

npm install -g @nebula-ai/mcp-server

Then configure your client to use stdio transport with the local server. This is useful for:

Offline access to your MCP tools
Custom server implementations
Development and testing

Next Steps

Memory Operations - Learn what you can do with memories
Python SDK - Build with the Python SDK
JavaScript SDK - Build with the Node.js SDK

Get Started

Core Guides

Advanced Guides

Integration

MCP Integration

MCP Integration

Quick Setup

Configuration

Available Tools

`add_memory`

`search_memories`

Troubleshooting

Web-Hosted vs Local Installation

Web-Hosted (Recommended)

Local Installation (Optional)

Next Steps

Get Started

Core Guides

Advanced Guides

Integration

​MCP Integration

​Quick Setup

​Configuration

​Available Tools

​add_memory

​search_memories

​Troubleshooting

​Web-Hosted vs Local Installation

​Web-Hosted (Recommended)

​Local Installation (Optional)

​Next Steps

MCP Integration

Quick Setup

Configuration

Available Tools

`add_memory`

`search_memories`

Troubleshooting

Web-Hosted vs Local Installation

Web-Hosted (Recommended)

Local Installation (Optional)

Next Steps