Per-Project Workspace Routing

By default, your Neuroloom OAuth token contains a single workspace_id baked into it — the workspace you selected during the initial consent flow. Every project you open with the same MCP client shares that workspace.

This is fine when you have one project. When you have three — a personal blog, a company API, an open-source library — memories from each bleed into searches for the others.

Neuroloom supports workspace routing via an X-Workspace-Id HTTP header. Send the header with any request, and Neuroloom routes that request to the specified workspace regardless of what workspace is embedded in your token. One OAuth login covers every workspace you're a member of.

Find your workspace_id

Your workspace_id is a UUID that looks like a1b2c3d4-e5f6-7890-abcd-ef1234567890.

From the dashboard: navigate to app.neuroloom.dev/settings/workspace. The workspace_id is listed under the workspace name.

From the API: call the workspace info endpoint with your API key:

curl https://api.neuroloom.dev/api/v1/workspaces/mine/insight \
  -H "Authorization: Token $NEUROLOOM_API_KEY"

The response includes workspace_id at the top level:

{
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "total_memories": 312,
  ...
}

If you have multiple workspaces, list them all:

curl https://api.neuroloom.dev/api/v1/workspaces/mine \
  -H "Authorization: Bearer $NEUROLOOM_OAUTH_TOKEN"

Claude Code (without the plugin)

If you're using Claude Code with direct MCP access rather than the plugin, add the X-Workspace-Id header to your project's .mcp.json:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "X-Workspace-Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}

Place this file in your project root. Each project directory gets its own .mcp.json with its own workspace_id. Claude Code reads this file when it starts and sends the header with every MCP request automatically.

You can also set this from the command line (writes to your user-scoped config, not the project file):

claude mcp add-json neuroloom -s user \
  '{"type":"http","url":"https://mcp.neuroloom.dev/mcp","headers":{"Authorization":"Bearer $NEUROLOOM_OAUTH_TOKEN","X-Workspace-Id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}'

Cursor

Add the X-Workspace-Id header to your Cursor MCP configuration at .cursor/mcp.json:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "X-Workspace-Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}

Use this config when using API key auth with Cursor (the workaround). Note that X-Workspace-Id is not included — API keys are already workspace-scoped by their binding, so the header is ignored:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Token your_api_key_here"
      }
    }
  }
}

VS Code / GitHub Copilot

VS Code reads MCP server configuration from .vscode/mcp.json in your project directory. Add the X-Workspace-Id header there:

{
  "servers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer $NEUROLOOM_OAUTH_TOKEN",
        "X-Workspace-Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}

Reload the VS Code window after editing this file (Cmd+Shift+P → "Developer: Reload Window") for the new headers to take effect.

Windsurf

Windsurf reads MCP configuration from .windsurfrc or the Windsurf settings panel. Add the header in the MCP server entry:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer $NEUROLOOM_OAUTH_TOKEN",
        "X-Workspace-Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}

The exact configuration file path depends on your Windsurf version. Check Windsurf's MCP documentation if this path has changed since this guide was written.

Verify the routing is working

After adding the header, confirm that requests are landing in the right workspace. Call memory_search with a query that should match memories in the target workspace:

Use memory_search with query "project architecture"

curl -X POST https://api.neuroloom.dev/api/v1/memories/search \
  -H "Authorization: Bearer $NEUROLOOM_OAUTH_TOKEN" \
  -H "X-Workspace-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{"query": "project architecture", "limit": 3}'

If the search returns results from the wrong workspace, verify that:

1. The workspace_id in the header exactly matches the target workspace's ID (no trailing spaces, correct UUID format)
2. Your account is a member of the target workspace (see workspace isolation)
3. The MCP client is actually sending the header — some clients cache connection details and require a restart

How workspace routing works

The X-Workspace-Id header overrides the workspace embedded in your OAuth token. When the header is present, Neuroloom:

1. Validates the header value is a valid UUID
2. Checks that your authenticated account is a member of the specified workspace
3. Routes the request to that workspace

If you are not a member of the specified workspace, the API returns 403 Forbidden. If the header contains a malformed UUID, the API returns 400 Bad Request.

When the header is absent, the token's embedded workspace_id is used — your default workspace. Existing users who don't send the header see no change in behavior.

Multi-workspace patterns

Per-project isolation (recommended): one workspace per repository. Each project's .mcp.json points to its workspace. Memories stay focused; searches return relevant results without noise from unrelated projects.

Per-environment isolation: separate workspaces for staging and production memory stores. Development sessions capture decisions into the dev workspace without polluting the production memory base.

Per-team isolation: in a team setting, each sub-team maintains its own workspace. The architecture team's decisions don't appear in the frontend team's searches.

See Workspace Isolation for the full model, including plan limits on workspace count.

Related pages

• Workspace Isolation — how workspaces work, what's isolated, plan limits
• Quickstart — initial setup, API keys, and first memory
• MCP Tools Reference — full tool reference