Connecting External Clients

NimbleBrain can act as a tool server for external apps that speak the MCP protocol, like Claude Desktop, Claude Code, Cursor, or VS Code. Point a client at your instance, name a workspace, and every tool from every app installed there becomes available inside that client, without switching to the web UI.

NimbleBrain exposes a single programmatic surface for this: the /mcp Streamable HTTP endpoint. For the protocol-level reference (methods, sessions, OAuth discovery), see The /mcp Endpoint.

How it connects

Authentication uses OAuth. There is no static API key to copy around. When you point a client at NimbleBrain:

1. The client hits /mcp without credentials and gets a 401 with a WWW-Authenticate header pointing to NimbleBrain’s discovery endpoint.
2. The client follows RFC 9728 / RFC 8414 discovery to find the authorization server (AuthKit).
3. A browser window opens for you to log in.
4. The client receives a JWT and attaches it on subsequent requests.

Clients that support MCP OAuth discovery (Claude Code, Claude Desktop, Cursor) handle all of this automatically.

What you need

• Instance URL — the address of your NimbleBrain instance (for example, https://your-team.nimblebrain.ai). Append /mcp to form the endpoint URL.
• Workspace ID — the X-Workspace-Id header that scopes the session to one workspace. Find it under Settings → This Workspace → General in the “MCP Connection” card.

Where workspace context comes from

A NimbleBrain /mcp session is bound to your identity, but each request names its workspace with the X-Workspace-Id header — validated against your membership. tools/list returns that workspace’s tools (named <source>__<tool>, for example crm__search) plus your identity tools (conversations__*, files__*, automations__*). Your own personal connectors carry a my_ marker (my_gmail__send) so they stay distinguishable from a workspace connector of the same name — they are different accounts. No tool name can address another workspace: the older ws_<id>-<source>__<tool> form is retired, and presenting one is refused with -32602 invalid_tool_name. A request with no (or a non-member) X-Workspace-Id reaches identity tools only, and a workspace tool is refused with -32602 workspace_access_denied.

If you send no X-Workspace-Id (or one you aren’t a member of), the session exposes identity tools only. Clients that can’t set a header still get a usable, identity-scoped surface.

Note

OAuth requires the workos auth adapter with an authkitDomain configured. On a dev-mode instance (no instance.json), the /mcp endpoint is open and no login is needed. See The /mcp Endpoint and auth adapters for the full setup.

Claude Code

Use the CLI:

claude mcp add --transport http nimblebrain https://your-team.nimblebrain.ai/mcp

Or add to your project’s .mcp.json:

.mcp.json

{
  "mcpServers": {
    "nimblebrain": {
      "type": "http",
      "url": "https://your-team.nimblebrain.ai/mcp"
    }
  }
}

The first request triggers the OAuth flow. Claude Code opens a browser for you to authenticate against AuthKit, then attaches the returned JWT on every subsequent request.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

claude_desktop_config.json

{
  "mcpServers": {
    "nimblebrain": {
      "type": "http",
      "url": "https://your-team.nimblebrain.ai/mcp"
    }
  }
}

The first time Claude Desktop uses the server, it opens a browser for OAuth login.

Cursor

Open Cursor Settings → MCP → Add Server, choose the HTTP/URL-based server type, and set the URL to https://your-team.nimblebrain.ai/mcp. Cursor handles the OAuth flow automatically. See Cursor’s MCP documentation for the latest details.

Other MCP clients

Any client that implements Streamable HTTP transport and either OAuth 2.0 (RFC 9728/8414 discovery) or a pre-issued bearer token can connect. See The /mcp Endpoint for the protocol-level reference, including the discovery endpoints and the manual OAuth flow.

What’s exposed

When an external client connects, it gets the tools installed in the workspace it named with X-Workspace-Id, plus your identity tools — the same tools the agent uses in the web UI. The client sees a flat tool list; NimbleBrain routes each call to the right app internally based on the namespaced tool name.

Two filters apply:

• Feature flags — tools gated by a disabled flag (for example, the skills__* authoring tools when skillManagement is false) are hidden. See Feature Flags.
• Role — admin-only tools (such as nb__manage_users, nb__manage_workspaces) are hidden from non-admin members.

If an admin installs or removes an app, the change is reflected on the next tools/list call.