@beforemerge/mcp

A Model Context Protocol (MCP) server that exposes your BeforeMerge organization's knowledge base, rules, findings, and specs to AI agents (Claude Code, Claude Desktop, Cursor, etc.) over stdio.

It runs locally on your machine and authenticates to the BeforeMerge v1 API with an API key — no hosted endpoint required.

Tools

| Tool | API endpoint | Description | |------|--------------|-------------| | search_knowledge | GET /api/v1/public/search?type=knowledge | Search org-private + platform-public knowledge by query | | list_rules | GET /api/v1/public/rules | List public rules (filter by search/category/impact) | | get_rule | GET /api/v1/public/rules/{slug} | Fetch a single rule by slug | | get_findings | GET /api/v1/public/findings | List your org's scan findings (filter by repository_id/severity/is_suppressed/is_baseline) | | list_specs | GET /api/v1/public/specs | List your org's specs (filter by search/status) | | install_content | GET /api/v1/public/install/{type}/{slug} | Render install files for a content item + platform |

All authenticated tools send Authorization: Bearer <BEFOREMERGE_API_KEY>.

Configuration

| Env var | Required | Default | |---------|----------|---------| | BEFOREMERGE_API_KEY | yes | — (a bm_… key with the relevant read:* scopes) | | BEFOREMERGE_API_URL | no | https://www.beforemerge.com/api/v1/public |

Your API key needs the scopes for the tools you use: read:knowledge, read:rules, read:findings, read:specs, and search.

Run

npx @beforemerge/mcp

Wire into Claude Code

Add to your Claude Code MCP config (e.g. ~/.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "beforemerge": {
      "command": "npx",
      "args": ["-y", "@beforemerge/mcp"],
      "env": {
        "BEFOREMERGE_API_KEY": "bm_your_key_here"
      }
    }
  }
}

To point at a non-production API (e.g. local dev), add "BEFOREMERGE_API_URL" to env.

Wire into Claude Desktop

Add the same block to claude_desktop_config.json under mcpServers.

Development

pnpm --filter @beforemerge/mcp build      # tsup → dist/
pnpm --filter @beforemerge/mcp test       # node:test (pure request-builder + mapping tests, no network)
pnpm --filter @beforemerge/mcp type-check

The request-building and response-mapping logic lives in src/api-client.ts as pure functions and is fully unit-tested without any live network calls. src/index.ts is the stdio entrypoint.