Sourcebot MCP server

The @sourcebot/mcp npm package has been deprecated as of 2026-03-04. Please migrate to using the streamable http transport.

The Sourcebot MCP Server connects AI tools to your Sourcebot deployment. This gives AI agents and automations the ability to search, read files, resolve references & definitions, and more across all of your code hosted on Sourcebot.

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.
Effort estimation and impact analysis: Validate vendor estimates and analyze change impact across hundreds of repositories.

Getting Started

Sourcebot MCP uses a 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 an active Enterprise license.
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 section.

If 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

Claude Code MCP docsRun the following command:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

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.

claude mcp add --transport http sourcebot https://sb.example.com/api/mcp \
  --header "Authorization: Bearer <key>"

Replace https://sb.example.com with wherever your Sourcebot instance is hosted, and <key> with an API key generated in Settings → API Keys.

Cursor

Cursor MCP docsGo to: Settings -> Cursor Settings -> Tools & MCP -> New MCP ServerPaste the following into your ~/.cursor/mcp.json file:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

{
    "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.

{
    "mcpServers": {
        "sourcebot": {
            "type": "http",
            "url": "https://sb.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer <key>"
            }
        }
    }
}

Replace https://sb.example.com with wherever your Sourcebot instance is hosted, and <key> with an API key generated in Settings → API Keys.

VS Code

VS Code MCP docsAdd the following to your .vscode/mcp.json file:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

{
    "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.

{
    "servers": {
        "sourcebot": {
            "type": "http",
            "url": "https://sb.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer <key>"
            }
        }
    }
}

Replace https://sb.example.com with wherever your Sourcebot instance is hosted, and <key> with an API key generated in Settings → API Keys.

Codex

Codex MCP docsAdd the following to your ~/.codex/config.toml file:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

[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:

codex mcp login sourcebot

[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:

export SOURCEBOT_API_KEY=<key>

Generate an API key in Settings → API Keys.

OpenCode

OpenCode MCP docsAdd the following to your opencode.jsonc file:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

{
    "$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:

opencode mcp auth sourcebot

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sourcebot": {
            "type": "remote",
            "url": "https://sb.example.com/api/mcp",
            "oauth": false,
            "headers": {
                "Authorization": "Bearer <key>"
            }
        }
    }
}

Replace https://sb.example.com with wherever your Sourcebot instance is hosted, and <key> with an API key generated in Settings → API Keys.

Windsurf

Windsurf MCP docsGo to: Windsurf Settings -> Cascade -> Add Server -> Add Custom ServerPaste the following into your ~/.codeium/windsurf/mcp_config.json file:

OAuth
API Key

is only available with an active Enterprise license. Please add your license key to activate it.

{
    "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.

{
    "mcpServers": {
        "sourcebot": {
            "serverUrl": "https://sb.example.com/api/mcp",
            "headers": {
                "Authorization": "Bearer <key>"
            }
        }
    }
}

Replace https://sb.example.com 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. If 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. When 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

is only available with an active Enterprise license. Please add your license key to activate it.

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 <key> header when connecting to the MCP server.

Available Tools

`search_code`

Searches for code that matches the provided search query as a substring by default, or as a regular expression if useRegex is true. Parameters:

Name	Required	Description
`query`	yes	The search pattern to match against code contents. Do not escape quotes in your query.
`useRegex`	no	Whether to use regular expression matching. When false, substring matching is used (default: false).
`filterByRepos`	no	Scope the search to specific repositories.
`filterByLanguages`	no	Scope the search to specific languages.
`filterByFilepaths`	no	Scope the search to specific filepaths.
`caseSensitive`	no	Whether the search should be case sensitive (default: false).
`includeCodeSnippets`	no	Whether to include code snippets in the response (default: false).
`ref`	no	Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch.
`maxTokens`	no	The maximum number of tokens to return (default: 10000).

`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. 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.

`list_tree`

Lists files and directories from a repository path. Can be used as a directory listing tool (depth: 1) or a repo-tree tool (depth > 1). 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).

`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).

Getting Started

Features

Configuration

Upgrade

Sourcebot MCP server

Use cases

Getting Started

Authorization

OAuth 2.0

API Key (Bearer token)

Available Tools

`search_code`

`list_repos`

`read_file`

`list_tree`

`list_commits`

`list_language_models`

`ask_codebase`

Getting Started

Features

Configuration

Upgrade

​Use cases

​Getting Started

​Authorization

​OAuth 2.0

​API Key (Bearer token)

​Available Tools

​search_code

​list_repos

​read_file

​list_tree

​list_commits

​list_language_models

​ask_codebase

Use cases

Getting Started

Authorization

OAuth 2.0

API Key (Bearer token)

Available Tools

`search_code`

`list_repos`

`read_file`

`list_tree`

`list_commits`

`list_language_models`

`ask_codebase`