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

# Connect a client

Sourcebot MCP uses a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport hosted at the `/api/mcp` route. Two authorization mechanisms are supported:

* **OAuth (preferred)**: MCP clients that support OAuth 2.0 will automatically handle the authorization flow and issue a short lived access token. No API key or manual token management required.
* **API key**: Any MCP client can authorize using a Sourcebot API key passed as a `Authorization: Bearer <key>` header. Create one in **Settings → API Keys**.

You can read more about the options in the [authorization](#authorization) section below.

> [!TIP]
>
> **Fastest setup:** Open **Settings → Account → MCP** in your Sourcebot deployment to copy the Server URL and use one-click install cards for supported clients.

> [!NOTE]
>
> Note the following about these examples:
>
> * The examples add the MCP server and connect it to Sourcebot's public deployment at [app.sourcebot.dev](https://app.sourcebot.dev). Replace the URL with your own Sourcebot deployment as needed.

> [accordion] Claude Code
>
> [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#connect-claude-code-to-tools-via-mcp)
>
> Run the following command:
>
> > [tab] OAuth
> >
> > ```sh theme={null}
> > claude mcp add --transport http sourcebot https://app.sourcebot.dev/api/mcp
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. Claude Code will automatically handle the OAuth 2.0 authorization flow the first time you connect.
>
> > [tab] API Key
> >
> > ```sh theme={null}
> > claude mcp add --transport http sourcebot https://app.sourcebot.dev/api/mcp \
> >   --header "Authorization: Bearer <key>"
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, and `<key>` with an API key generated in **Settings → API Keys**.

> [accordion] Cursor
>
> [Cursor MCP docs](https://cursor.com/docs/context/mcp)
>
> Go to: `Settings` -> `Cursor Settings` -> `Tools & MCP` -> `New MCP Server`
>
> Paste the following into your `~/.cursor/mcp.json` file:
>
> > [tab] OAuth
> >
> > ```json theme={null}
> > {
> >     "mcpServers": {
> >         "sourcebot": {
> >             "type": "http",
> >             "url": "https://app.sourcebot.dev/api/mcp"
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. Cursor will automatically handle the OAuth 2.0 authorization flow the first time you connect.
>
> > [tab] API Key
> >
> > ```json theme={null}
> > {
> >     "mcpServers": {
> >         "sourcebot": {
> >             "type": "http",
> >             "url": "https://app.sourcebot.dev/api/mcp",
> >             "headers": {
> >                 "Authorization": "Bearer <key>"
> >             }
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, and `<key>` with an API key generated in **Settings → API Keys**.

> [accordion] VS Code
>
> [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
>
> Add the following to your [.vscode/mcp.json](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server-to-your-workspace) file:
>
> > [tab] OAuth
> >
> > ```json theme={null}
> > {
> >     "servers": {
> >         "sourcebot": {
> >             "type": "http",
> >             "url": "https://app.sourcebot.dev/api/mcp"
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. VS Code will automatically handle the OAuth 2.0 authorization flow the first time you connect.
>
> > [tab] API Key
> >
> > ```json theme={null}
> > {
> >     "servers": {
> >         "sourcebot": {
> >             "type": "http",
> >             "url": "https://app.sourcebot.dev/api/mcp",
> >             "headers": {
> >                 "Authorization": "Bearer <key>"
> >             }
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, and `<key>` with an API key generated in **Settings → API Keys**.

> [accordion] Codex
>
> [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp)
>
> > [tab] OAuth
> >
> > Run the following command:
> >
> > ```sh theme={null}
> > codex mcp add sourcebot --url https://app.sourcebot.dev/api/mcp
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. Codex will automatically detect OAuth support and prompt you to authorize in your browser when you first connect.
> >
> > > [!TIP]
> > >
> > > Open **Settings → Account → MCP** in your Sourcebot deployment and click **Copy command** on the Codex card for a ready-to-run command with the correct Server URL.
>
> > [tab] API Key
> >
> > Run the following command:
> >
> > ```sh theme={null}
> > codex mcp add sourcebot --url https://app.sourcebot.dev/api/mcp --bearer-token-env-var SOURCEBOT_API_KEY
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, then set your API key as an environment variable:
> >
> > ```sh theme={null}
> > export SOURCEBOT_API_KEY=<key>
> > ```
> >
> > Generate an API key in **Settings → API Keys**.

> [accordion] OpenCode
>
> [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers)
>
> Add the following to your `opencode.jsonc` file:
>
> > [tab] OAuth
> >
> > ```json theme={null}
> > {
> >     "$schema": "https://opencode.ai/config.json",
> >     "mcp": {
> >         "sourcebot": {
> >             "type": "remote",
> >             "url": "https://app.sourcebot.dev/api/mcp"
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. OpenCode will automatically handle the OAuth 2.0 authorization flow the first time you connect. You can also manually trigger it with:
> >
> > ```sh theme={null}
> > opencode mcp auth sourcebot
> > ```
>
> > [tab] API Key
> >
> > ```json theme={null}
> > {
> >     "$schema": "https://opencode.ai/config.json",
> >     "mcp": {
> >         "sourcebot": {
> >             "type": "remote",
> >             "url": "https://app.sourcebot.dev/api/mcp",
> >             "oauth": false,
> >             "headers": {
> >                 "Authorization": "Bearer <key>"
> >             }
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, and `<key>` with an API key generated in **Settings → API Keys**.

> [accordion] Windsurf
>
> [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
>
> Go to: `Windsurf Settings` -> `Cascade` -> `Add Server` -> `Add Custom Server`
>
> Paste the following into your `~/.codeium/windsurf/mcp_config.json` file:
>
> > [tab] OAuth
> >
> > ```json theme={null}
> > {
> >     "mcpServers": {
> >         "sourcebot": {
> >             "serverUrl": "https://app.sourcebot.dev/api/mcp"
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted. Windsurf will automatically handle the OAuth 2.0 authorization flow the first time you connect.
>
> > [tab] API Key
> >
> > ```json theme={null}
> > {
> >     "mcpServers": {
> >         "sourcebot": {
> >             "serverUrl": "https://app.sourcebot.dev/api/mcp",
> >             "headers": {
> >                 "Authorization": "Bearer <key>"
> >             }
> >         }
> >     }
> > }
> > ```
> >
> > Replace `https://app.sourcebot.dev` with wherever your Sourcebot instance is hosted, and `<key>` with an API key generated in **Settings → API Keys**.

## Authorization

The Sourcebot MCP server supports two authorization methods: OAuth and API keys.

Regardless of which method you use, all MCP requests are scoped to the associated Sourcebot user and inherit the [user's role and permissions](https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions.md). When [permission syncing](https://docs.sourcebot.dev/docs/features/permission-syncing.md) is configured, this includes repository permissions - the MCP server will only surface results from repositories the user has access to.

With the [MCP Gateway](https://docs.sourcebot.dev/docs/mcp/gateway.md), both methods can also call the user's allowed connector tools, such as Linear.

### OAuth 2.0

Sourcebot implements an OAuth 2.0 authorization server with support for dynamic client registration (RFC 7591). This means MCP clients can register themselves automatically without any manual setup. Just point your client at the MCP endpoint and it will handle the full authorization flow, prompting you to log in and approve access in your browser the first time you connect. No API key or manual token management is required.

Once authorized, Sourcebot issues a short-lived access token (valid for 1 hour) and a refresh token (valid for 90 days). The MCP client handles token refresh automatically, so you stay connected without needing to re-authorize.

![OAuth authorization prompt showing Cursor requesting access to a Sourcebot account](https://mintcdn.com/sourcebot/4jRqIKFzMtH-0zb0/images/mcp_oauth_authorize.png?fit=max\&auto=format\&n=4jRqIKFzMtH-0zb0\&q=85\&s=33c2d2df8219f5b0b84df2455558a6a3)

### API Key (Bearer token)

API keys provide a simpler alternative to OAuth that works with any MCP client. Each key is scoped to the user who created it and inherits their permissions. To create one, go to **Settings → API Keys** and click **New API key**.

Pass the key as an `Authorization: Bearer <key>` header when connecting to the MCP server.

![API Keys page in Sourcebot Settings](https://mintcdn.com/sourcebot/4jRqIKFzMtH-0zb0/images/mcp_api_key_settings.png?fit=max\&auto=format\&n=4jRqIKFzMtH-0zb0\&q=85\&s=2cda13194ede64f478f5447b8f8be12c)


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