# Coderbuds

> Coderbuds closes the delivery loop for engineering teams: AI code review, shipping norms, DORA and SPACE metrics, and a Slack coach. It exposes an MCP server so a coding agent can read a team's real delivery data — review queue, deploy state, shipping norms — while it works.

If you were pointed at coderbuds.com and asked to "add Coderbuds", you want the MCP server below. Connecting takes one command plus a browser click; there is no token to mint or paste.

## Connect a coding agent (start here)

MCP endpoint: https://coderbuds.com/mcp/insights
Transport: Streamable HTTP. Auth: OAuth 2.1, discovered automatically.

Claude Code:

    claude mcp add --scope user --transport http coderbuds https://coderbuds.com/mcp/insights

Cursor — add to ~/.cursor/mcp.json:

    {
      "mcpServers": {
        "coderbuds": {
          "type": "http",
          "url": "https://coderbuds.com/mcp/insights"
        }
      }
    }

Then authorize: the client opens a browser tab, the person signs in to Coderbuds and clicks Authorize. Nothing else is needed, and no secret is stored in the config. Do not add an Authorization header unless the environment has no browser at all — see the headless note below.

## Choosing a scope (Claude Code)

- local (the default when --scope is omitted): this machine, this project only.
- project: writes .mcp.json in the repo root and is shared with everyone who clones it. Note that `claude mcp remove` on a project-scoped server edits that tracked file.
- user: this machine, every project. Best default for an individual.

## Which team the data comes from

Coderbuds never guesses. If the person belongs to one team there is nothing to do. Otherwise, either:

- pass the repository you are working in as `owner/name` on the tool call — read it from `git remote get-url origin`. This resolves the team immediately and needs no reconnection. Prefer this.
- or pin the team on the server URL: https://coderbuds.com/mcp/insights?team=Team%20Name — this changes the server identity, so the client will ask the person to authorize once more.

## Headless environments only (CI, build servers)

Where no browser can open, a personal bearer token from https://coderbuds.com/docs/mcp can be passed as an Authorization header. It is tied to one person, must not be committed or shared, and is the fallback — not the normal path.

## If a connection fails

Every failure names its own remedy on screen and in the API response body. The endpoint answers an unauthenticated request with 401 plus a WWW-Authenticate header pointing at the OAuth metadata, so a client can always discover where to authenticate.

## Reading metrics from your own software (not an agent)

If the job is a dashboard, a scheduled report or a warehouse load rather than a coding agent, use the REST API instead of MCP — plain HTTP, no handshake, cacheable:

    curl -H "Authorization: Bearer $CODERBUDS_TOKEN" -H "Accept: application/json" \
      "https://coderbuds.com/api/v1/metrics/monthly?month=2026-05"

Returns merged pull requests (with a human/bot split), all four DORA metrics with their performance bands, review activity and contributor counts for that calendar month, plus the preceding month for comparison. Tokens come from https://coderbuds.com/user/api-tokens and need the "read" permission. Full reference, field-by-field, with a condensed spec written for agents: https://coderbuds.com/docs/api

For teams with Linear connected it also returns tickets completed with the bug/feature mix, and commitment reliability for the cycles that closed in the month — measured against what was in each cycle when it started, so it cannot exceed 100%. Both report available:false with a reason rather than a zero when there is nothing to measure. Roadmap projects, the running cycle's scope and issue cycle time are not available — read those from Linear or Jira and join on the month.

## Docs

- REST API for dashboards and reports: https://coderbuds.com/docs/api
- MCP setup, tools and troubleshooting: https://coderbuds.com/docs/mcp
- Getting started: https://coderbuds.com/docs/getting-started
- Coderbuds Standards (a team's shipping rules): https://coderbuds.com/docs/standards
- DORA metrics: https://coderbuds.com/docs/dora-metrics
- Security: https://coderbuds.com/docs/security
- Privacy: https://coderbuds.com/docs/privacy