> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a client

> Add Orbb to Claude, ChatGPT, Cursor, Claude Code, or any MCP client.

Every client takes the same thing: a server URL. Most then open a browser for you to sign in to Orbb, and calls arrive as you.

| Server | URL |
| - | - |
| Orbb Research | `https://mcp.orbb.com/mcp/research` |
| Your workspace | `https://mcp.orbb.com/mcp` |

> [tab] Claude
>
> In claude.ai or the desktop app, open **Settings → Connectors → Add custom connector**, paste the server URL, and choose **Connect**. A browser window opens the Orbb sign-in.
>
> An organization owner can add the connector once for the whole team; each person then signs in as themselves.

> [tab] ChatGPT
>
> On a plan with connectors, open **Settings → Connectors**, add a custom connector with the server URL, and sign in to Orbb when asked.

> [tab] Claude Code
>
> With OAuth:
>
> ```bash theme={null}
> claude mcp add --transport http orbbai https://mcp.orbb.com/mcp/research
> ```
>
> Then run `/mcp`, pick `orbbai`, and choose **Authenticate**.
>
> With an API key, for scripts and CI where no browser can open:
>
> ```bash theme={null}
> claude mcp add --transport http orbbai https://mcp.orbb.com/mcp/research \
>   --header "Authorization: Bearer $ORBB_API_KEY"
> ```

> [tab] Cursor
>
> Add the server to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "orbbai": {
>       "url": "https://mcp.orbb.com/mcp/research"
>     }
>   }
> }
> ```
>
> Cursor opens the sign-in the first time a tool is used. To use a key instead, add `"headers": { "Authorization": "Bearer orbb_sk_..." }`.

> [tab] Your own agent
>
> Any MCP client library that speaks Streamable HTTP works. With an API key:
>
> ```python theme={null}
> from mcp import ClientSession
> from mcp.client.streamable_http import streamablehttp_client
>
> async with streamablehttp_client(
>     "https://mcp.orbb.com/mcp/research",
>     headers={"Authorization": f"Bearer {ORBB_API_KEY}"},
> ) as (read, write, _):
>     async with ClientSession(read, write) as session:
>         await session.initialize()
>         tools = await session.list_tools()
>         answer = await session.call_tool(
>             "orbbai_who_knows_them",
>             {"person": "Maya Okafor", "company": "Northwind Labs", "about": "engineering"},
>         )
> ```
>
> Or let the agent install it. Paste this into it:
>
> ```text theme={null}
> Add Orbb Research to this environment as an MCP server, then verify it works.
> The server is https://mcp.orbb.com/mcp/research and it uses OAuth: install it the
> way this environment installs an MCP server, then sign me in. If you cannot open
> a browser, stop and ask me for an Orbb API key, sent as "Authorization: Bearer <key>".
> Once connected, list the Orbb tools you can see and say what each does in one line.
> ```

## Signing in

> [accordion] OAuth
>
> Both servers are OAuth 2.1 resource servers. An unauthenticated call is answered `401` with a `WWW-Authenticate` header pointing at the server's protected-resource metadata, which names the authorization server; clients register themselves dynamically. You only paste the URL.
>
> The workspace server also needs your organization to have MCP access turned on. Without it, every tool answers *"MCP access is not enabled for this organization."* — ask your Orbb admin.

> [accordion] API key (Orbb Research only)
>
> Send `Authorization: Bearer orbb_sk_…` — the same key the [API](https://docs.orbb.com/api/authentication.md) takes, created under [API keys](https://platform.orbb.com/console/keys). Research runs are charged to that key's account.
>
> | Answer | Means |
> | - | - |
> | `401` *"This API key was refused."* | Unknown, revoked or expired. Create a new one. |
> | `503` *"Your key could not be checked right now. This is not a refusal"* | Try again shortly. |
>
> The workspace server does not take keys.

> [!WARNING]
>
> **A plan belongs to the credential that made it.** Orbb Research keeps one conversation per API key, or per signed-in person, and a plan can only be started from that conversation. An agent that plans with one key and starts with another gets *plan not found*.

## Check it works

Ask your assistant: *"Using Orbb, what can you answer?"* It should call `orbbai_capabilities` and describe what Orbb covers and what it needs your own data for.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.