Skip to content

BSR MCP server#

The Buf Schema Registry (BSR) exposes a Model Context Protocol (MCP) server so AI agents can call BSR APIs on your behalf. Your agents can find a module, fetch its schema, inspect commits and labels, or call any other BSR API without you leaving the session.

The server lives at https://buf.build/mcp and speaks MCP over HTTP. On a private BSR instance, the server is reachable at https://your-bsr-instance.example.com/mcp.

The server supports two ways to authenticate: - Browser-based OAuth2 for interactive use, where the first time a client connects you approve it in your browser and your agent stores an API token locally - A pre-existing BSR API token passed in a header, mostly intended for bots and CI.

What the server exposes#

The server exposes the BSR Registry API, with the v1 services for modules, owners, commits, and labels as MCP tools. For the full method list and schemas, see the Registry API documentation or the Invoking BSR APIs page.

The token a client receives has the same access as the user who approved it, so any RPC you can call from the web UI or the Buf CLI is callable through MCP, including writes.

Connect an MCP client#

Any MCP client that supports HTTP transport and OAuth2 can connect to https://buf.build/mcp. The first time a client connects, it opens your browser to a consent page. Approve the access once and the client caches the token for future sessions.

The commands below add the server for the most common coding agents. For any other client, follow its instructions for adding a remote MCP server and use https://buf.build/mcp as the URL.

Claude Code:

$ claude mcp add --transport http bsr https://buf.build/mcp

This adds the server to the current project only. Pass --scope user to make it available across all your projects.

Codex:

$ codex mcp add bsr --url https://buf.build/mcp

This writes to your global ~/.codex/config.toml, so the server is available in every project. If the browser consent page doesn’t open automatically, run codex mcp login bsr.

OpenCode:

Add the server under the mcp key in your opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bsr": {
      "type": "remote",
      "url": "https://buf.build/mcp",
      "enabled": true
    }
  }
}

Then run opencode mcp auth bsr to complete the OAuth2 flow. OpenCode handles authentication automatically using dynamic client registration. Adding the server to the project’s opencode.json scopes it to that project, while ~/.config/opencode/opencode.json makes it available everywhere.

Use a pre-existing token (bots and CI)#

The BSR’s OAuth2 flow requires browser-based user consent, which makes it unworkable for bots or CI jobs. For headless flows, skip OAuth2 and pass an existing BSR API token in the Authorization header.

Create the token from your account settings, see Create a token. On a private BSR instance, issue the token to a bot user so it survives staff changes.

With a token present, the client uses the supplied header instead of starting the OAuth2 flow. The token has the same access as the user or bot user it belongs to.

Claude Code:

$ claude mcp add --transport http bsr https://buf.build/mcp \
    --header "Authorization: Bearer <BUF_TOKEN>"

Codex:

$ codex mcp add bsr --url https://buf.build/mcp \
    --bearer-token-env-var BUF_TOKEN

OpenCode:

Set oauth to false and supply the header in your opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bsr": {
      "type": "remote",
      "url": "https://buf.build/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:BUF_TOKEN}"
      }
    }
  }
}
Most other clients accept a custom header when adding a remote MCP server. Consult your client’s configuration documentation for the exact syntax.

Manage authorized clients#

Each authorized client appears as an API token in your account settings with the name shown on the consent screen. To revoke access, delete the token. The client will then need to re-authorize on its next request. See Authentication for details on token management.

After revoking, remove the stale entry from the client (for example, claude mcp remove bsr) so it doesn’t keep retrying.

Further reading#