> ## 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. # Sourcebot MCP server export const feature_7 = "OAuth" export const verb_7 = undefined export const feature_6 = "OAuth" export const verb_6 = undefined export const feature_5 = "OAuth" export const verb_5 = undefined export const feature_4 = "OAuth" export const verb_4 = undefined export const feature_3 = "OAuth" export const verb_3 = undefined export const feature_2 = "OAuth" export const verb_2 = undefined export const feature_1 = "OAuth" export const verb_1 = undefined export const feature_0 = "The Sourcebot MCP server" export const verb_0 = undefined The Sourcebot MCP Server connects AI tools to your [Sourcebot deployment](/docs/deployment/docker-compose). This gives your agents the ability to search, read files, resolve references & definitions, and more across all of your code hosted on Sourcebot. {feature_0} {verb_0 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ## Use cases * **Context for local agents:** Plug the MCP into coding agents like Cursor, Claude Code, or Copilot to give them context across your entire codebase, not just the open workspace. * **Building autonomous AI agents:** Use Sourcebot as a code context layer for multi-agent systems that review PRs, auto-fix bugs, and answer questions across the company. ## Getting Started 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. Only available with a paid [subscription](/docs/activating-a-subscription). * **API key**: Any MCP client can authorize using a Sourcebot API key passed as a `Authorization: Bearer ` header. Create one in **Settings → API Keys**. You can read more about the options in the [authorization](#authorization) section. If [anonymous access](https://docs.sourcebot.dev/docs/configuration/auth/access-settings#anonymous-access) is enabled on your Sourcebot instance, no OAuth token or API key is required. You can connect directly to the MCP endpoint without any authorization. [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#connect-claude-code-to-tools-via-mcp) Run the following command: {feature_1} {verb_1 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```sh theme={null} claude mcp add --transport http sourcebot https://sb.example.com/api/mcp ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted. Claude Code will automatically handle the OAuth 2.0 authorization flow the first time you connect. ```sh theme={null} claude mcp add --transport http sourcebot https://sb.example.com/api/mcp \ --header "Authorization: Bearer " ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, and `` with an API key generated in **Settings → API Keys**. [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: {feature_2} {verb_2 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```json theme={null} { "mcpServers": { "sourcebot": { "type": "http", "url": "https://sb.example.com/api/mcp" } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted. Cursor will automatically handle the OAuth 2.0 authorization flow the first time you connect. ```json theme={null} { "mcpServers": { "sourcebot": { "type": "http", "url": "https://sb.example.com/api/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, and `` with an API key generated in **Settings → API Keys**. [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: {feature_3} {verb_3 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```json theme={null} { "servers": { "sourcebot": { "type": "http", "url": "https://sb.example.com/api/mcp" } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted. VS Code will automatically handle the OAuth 2.0 authorization flow the first time you connect. ```json theme={null} { "servers": { "sourcebot": { "type": "http", "url": "https://sb.example.com/api/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, and `` with an API key generated in **Settings → API Keys**. [Codex MCP docs](https://developers.openai.com/codex/mcp) Add the following to your `~/.codex/config.toml` file: {feature_4} {verb_4 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```toml theme={null} [mcp_servers.sourcebot] url = "https://sb.example.com/api/mcp" ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted. Then run the following to authenticate: ```sh theme={null} codex mcp login sourcebot ``` ```toml theme={null} [mcp_servers.sourcebot] url = "https://sb.example.com/api/mcp" bearer_token_env_var = "SOURCEBOT_API_KEY" ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, then set your API key as an environment variable: ```sh theme={null} export SOURCEBOT_API_KEY= ``` Generate an API key in **Settings → API Keys**. [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers) Add the following to your `opencode.jsonc` file: {feature_5} {verb_5 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "sourcebot": { "type": "remote", "url": "https://sb.example.com/api/mcp" } } } ``` Replace `https://sb.example.com` 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 ``` ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "sourcebot": { "type": "remote", "url": "https://sb.example.com/api/mcp", "oauth": false, "headers": { "Authorization": "Bearer " } } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, and `` with an API key generated in **Settings → API Keys**. [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: {feature_6} {verb_6 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ```json theme={null} { "mcpServers": { "sourcebot": { "serverUrl": "https://sb.example.com/api/mcp" } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted. Windsurf will automatically handle the OAuth 2.0 authorization flow the first time you connect. ```json theme={null} { "mcpServers": { "sourcebot": { "serverUrl": "https://sb.example.com/api/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Replace `https://sb.example.com` with wherever your Sourcebot instance is hosted, and `` with an API key generated in **Settings → API Keys**. ## Authorization The Sourcebot MCP server supports two authorization methods, OAuth and API keys. If [anonymous access](/docs/configuration/auth/access-settings#anonymous-access) is enabled on your instance, no authorization is required. Regardless of which method you use, all MCP requests are scoped to the associated Sourcebot user and inherit the [user's role and permissions](/docs/configuration/auth/roles-and-permissions). When [permission syncing](/docs/features/permission-syncing) is configured, this includes repository permissions - the MCP server will only surface results from repositories the user has access to. ### OAuth 2.0 {feature_7} {verb_7 ?? "is"} only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. 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 ### 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, navigate to **Settings → API Keys** and click **Create API Key**. Pass the key as an `Authorization: Bearer ` header when connecting to the MCP server. API Keys page in Sourcebot Settings ## Available Tools ### `grep` Searches for code matching a regular expression pattern across repositories, similar to `grep`/`ripgrep`. Always case-sensitive. Results are grouped by file and include line numbers. Parameters: | Name | Required | Description | | :-------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | `pattern` | yes | The regex pattern to search for in file contents. | | `path` | no | Directory path to scope the search to. Defaults to the repository root. | | `include` | no | File glob pattern to include in the search (e.g. `*.ts`, `*.{ts,tsx}`). | | `repo` | no | Repository name to search in. If not provided, searches all repositories. Use the full name including host (e.g. `github.com/org/repo`). | | `ref` | no | Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch. | | `limit` | no | Maximum number of matching files to return (default: 100). | ### `list_repos` Lists repositories indexed by Sourcebot with optional filtering and pagination. Parameters: | Name | Required | Description | | :---------- | :------- | :----------------------------------------------------------------------------- | | `query` | no | Filter repositories by name (case-insensitive). | | `page` | no | Page number for pagination (min 1, default: 1). | | `perPage` | no | Results per page for pagination (min 1, max 100, default: 30). | | `sort` | no | Sort repositories by 'name' or 'pushed' (most recent commit). Default: 'name'. | | `direction` | no | Sort direction: 'asc' or 'desc' (default: 'asc'). | ### `read_file` Reads the source code for a given file, with optional line range control for large files. Parameters: | Name | Required | Description | | :------- | :------- | :----------------------------------------------------------------------------------------------------- | | `repo` | yes | The repository name. | | `path` | yes | The path to the file. | | `ref` | no | Commit SHA, branch or tag name to fetch the source code for. If not provided, uses the default branch. | | `offset` | no | Line number to start reading from (1-indexed). Omit to start from the beginning. | | `limit` | no | Maximum number of lines to read (max: 500). Omit to read up to 500 lines. | ### `list_tree` Lists files and directories from a repository path. Directories are shown before files at each level. Parameters: | Name | Required | Description | | :------------------- | :------- | :------------------------------------------------------------------------------------------- | | `repo` | yes | The name of the repository to list files from. | | `path` | no | Directory path (relative to repo root). If omitted, the repo root is used. | | `ref` | no | Commit SHA, branch or tag name to list files from. If not provided, uses the default branch. | | `depth` | no | Number of directory levels to traverse below `path` (min 1, max 10, default: 1). | | `includeFiles` | no | Whether to include file entries in the output (default: true). | | `includeDirectories` | no | Whether to include directory entries in the output (default: true). | | `maxEntries` | no | Maximum number of entries to return before truncating (min 1, max 10000, default: 1000). | ### `list_commits` Get a list of commits for a given repository. Parameters: | Name | Required | Description | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------- | | `repo` | yes | The name of the repository to list commits for. | | `query` | no | Search query to filter commits by message content (case-insensitive). | | `since` | no | Show commits more recent than this date. Supports ISO 8601 (e.g., '2024-01-01') or relative formats (e.g., '30 days ago'). | | `until` | no | Show commits older than this date. Supports ISO 8601 (e.g., '2024-12-31') or relative formats (e.g., 'yesterday'). | | `author` | no | Filter commits by author name or email (case-insensitive). | | `ref` | no | Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch. | | `page` | no | Page number for pagination (min 1, default: 1). | | `perPage` | no | Results per page for pagination (min 1, max 100, default: 50). | ### `glob` Finds files whose paths match a glob pattern across repositories (e.g. `**/*.ts`, `src/**/*.test.{ts,tsx}`). Results are grouped by repository. Parameters: | Name | Required | Description | | :-------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | `pattern` | yes | Glob pattern to match file paths against (e.g. `**/*.ts`, `src/**/*.test.{ts,tsx}`). | | `path` | no | Restrict results to files under this subdirectory. | | `repo` | no | Repository name to search in. If not provided, searches all repositories. Use the full name including host (e.g. `github.com/org/repo`). | | `ref` | no | Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch. | | `limit` | no | Maximum number of files to return (default: 100). | ### `get_diff` Returns a structured diff between two refs in a repository using a two-dot comparison. Parameters: | Name | Required | Description | | :----- | :------- | :---------------------------------------------------------- | | `repo` | yes | The fully-qualified repository name. | | `base` | yes | The base git ref (branch, tag, or commit SHA) to diff from. | | `head` | yes | The head git ref (branch, tag, or commit SHA) to diff to. | ### `find_symbol_definitions` Finds where a symbol (function, class, variable, etc.) is defined in a repository. Parameters: | Name | Required | Description | | :------- | :------- | :----------------------------------------------------------------------------------------------------- | | `symbol` | yes | The symbol name to find definitions of. | | `repo` | yes | Repository name to scope the search to. Use the full name including host (e.g. `github.com/org/repo`). | ### `find_symbol_references` Finds all usages of a symbol (function, class, variable, etc.) across a repository. Parameters: | Name | Required | Description | | :------- | :------- | :----------------------------------------------------------------------------------------------------- | | `symbol` | yes | The symbol name to find references to. | | `repo` | yes | Repository name to scope the search to. Use the full name including host (e.g. `github.com/org/repo`). | ### `list_language_models` Lists the available language models configured on the Sourcebot instance. Use this to discover which models can be specified when calling `ask_codebase`. Parameters: This tool takes no parameters. ### `ask_codebase` Ask a natural language question about the codebase. This tool uses an AI agent to autonomously search code, read files, and find symbol references/definitions to answer your question. Returns a detailed answer in markdown format with code references, plus a link to view the full research session in the Sourcebot web UI. Parameters: | Name | Required | Description | | :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | yes | The query to ask about the codebase. | | `repos` | no | The repositories that are accessible to the agent during the chat. If not provided, all repositories are accessible. | | `languageModel` | no | The language model to use for answering the question. Object with `provider` and `model`. If not provided, defaults to the first model in the config. Use `list_language_models` to see available options. | | `visibility` | no | The visibility of the chat session (`'PRIVATE'` or `'PUBLIC'`). Defaults to `PRIVATE` for authenticated users and `PUBLIC` for anonymous users. Set to `PUBLIC` to make the chat viewable by anyone with the link (useful in shared environments like Slack). |