MCP Server Setup

Most MCP clients can be connected in about a minute. Use Cloud for the fastest path, or point a self-hosted client at your own Kumbukum instance.

Prerequisites

• A running Kumbukum instance
• A personal access token (generate in Settings > Tokens)

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
    "mcpServers": {
        "kumbukum": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://app.kumbukum.com/mcp"],
            "env": {
                "ACCESS-TOKEN": "your-access-token"
            }
        }
    }
}

HTTP Transport

For remote MCP access via Streamable HTTP:

The Cloud MCP endpoint is available at:

https://app.kumbukum.com/mcp

No additional setup required — the server is always running.

Environment Variables

Variable	Description	Default
ACCESS-TOKEN	Personal access token for stdio transport	—
API_BASE_URL	Base URL of the Kumbukum instance	http://localhost:3000
PROJECT-ID	Override default project for stdio	Auto-detected
PORT	HTTP transport port	3002

Shell syntax note

ACCESS-TOKEN and PROJECT-ID contain hyphens because they are read directly by the MCP server. In shell commands, pass them with env, for example:

env 'ACCESS-TOKEN'=your-access-token 'PROJECT-ID'=your-project-id API_BASE_URL=https://your-instance.com node apps/mcp/server.js

HTTP Transport Headers

When using the HTTP or SSE transport, pass your credentials as headers instead of environment variables:

• Authorization: Bearer <access-token> — recommended
• Authorization: Token <access-token> — also accepted
• access-token: <access-token> — alternative (mirrors Razuna MCP)
• X-Project-Id: <project-id> — optional, overrides the default project

Default Project

On startup, the MCP server calls GET /projects and picks the project with is_default: true. All create tools (create_note, store_memory, save_url) fall back to this project when project_id is omitted.

Set PROJECT-ID (passed via env for stdio) or the X-Project-Id header (HTTP/SSE) to override this behavior.