Connecting External Clients

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

Each workspace has its own endpoint, /mcp/<workspaceId>. For the protocol-level reference (methods, protocol revision, OAuth discovery, the audience rule), see The MCP Endpoint.

What you need

The workspace’s MCP URL. Open the workspace in NimbleBrain and go to Workspace settings → MCP, then copy the URL, for example https://nb.example.com/mcp/ws_0123456789abcdef. That URL is the whole configuration: it names the workspace, and it is what your login token will be bound to.

To use two workspaces from one client, add each URL as its own server.

Caution

The bare https://<instance>/mcp URL is not an endpoint; it answers 404 and names the URL shape to use. A client configured with it must be switched to a workspace’s URL.

How it connects

Authentication uses OAuth. There is no static API key to copy around. When you add the URL to a client:

1. The client calls the URL without credentials and gets a 401 pointing at that workspace’s discovery document.
2. The client follows RFC 9728 discovery to find the authorization server, and learns the resource to ask for: the workspace’s URL.
3. A browser window opens for you to log in.
4. The client receives a token bound to that URL and attaches it on subsequent requests.

Clients that support MCP OAuth discovery (Claude, Claude Code, Cursor) handle all of this automatically. The token is valid only at the URL it was issued for, and you reach the workspace only while you are a member of it.

Note

OAuth requires the workos auth adapter with an authkitDomain configured, and a resource indicator on the authorization server for each of the instance’s public hosts (see The MCP Endpoint). On a dev-mode instance (no instance.json), no login is needed. See auth adapters for the full setup.

Claude

In Claude, add a custom connector and paste the workspace’s MCP URL. Claude runs the OAuth flow the first time it connects.

Claude Code

Use the CLI:

claude mcp add --transport http nimblebrain https://nb.example.com/mcp/<workspaceId>

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

.mcp.json

{
  "mcpServers": {
    "nimblebrain": {
      "type": "http",
      "url": "https://nb.example.com/mcp/<workspaceId>"
    }
  }
}

The first request triggers the OAuth flow. Claude Code opens a browser for you to log in, then attaches the returned token on every subsequent request.

Cursor

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

Other MCP clients

Any client that speaks MCP 2026-07-28 over Streamable HTTP and implements OAuth 2.0 with resource indicators (RFC 9728 discovery, RFC 8707 resource) can connect. See The MCP Endpoint for the protocol-level reference, including the discovery endpoints and the manual OAuth flow.

What’s exposed

A client gets the tools installed in the workspace its URL names (named <source>__<tool>, for example crm__search), plus your identity tools (conversations__*, files__*, tasks__*) over that workspace’s data — the same tools the agent uses in the web UI. Your own personal connectors carry a my_ marker (my_gmail__send) so they stay distinguishable from a workspace connector of the same name. No tool name can reach another workspace; connect to that workspace’s URL instead.

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.
• App-only tools — tools the web app’s settings call and no agent does (org administration such as nb__manage_users and nb__manage_workspaces, and model configuration) are never listed, and an external client that calls one by name is refused. Administer the org from the web app.
• Role — a tool limited to org admins is hidden from other members.

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