MCP server and API

From an agent, or the API

Mergepatrol serves an MCP server at /mcp, so a coding agent can do anything the dashboard does: queue a PR, take it out, read where it is, review it, read the queue’s history, change a repo’s settings. Every call acts as a GitHub user or bot: Mergepatrol puts the labels on, comments, and reviews with their token, so GitHub checks they may.

An MCP client that supports OAuth signs in with GitHub in the browser, as the dashboard does:

claude mcp add --transport http mergepatrol https://mergepatrol.ai/mcp

The client gets a Mergepatrol session, and the GitHub token stays on the server. Mergepatrol sends the sign-in back only to a loopback address, where native clients such as Claude Code, Codex and Cursor listen.

An agent without a browser, such as one in CI, passes a GitHub token instead: one from gh auth token, a personal access token, or a workflow’s GITHUB_TOKEN. A fine-grained token also needs write access to issues or pull requests. Mergepatrol never stores the token. It remembers its hash, in memory for 5 minutes, so calls in a row do not each ask GitHub again.

claude mcp add --transport http mergepatrol https://mergepatrol.ai/mcp \
  --header "Authorization: Bearer $(gh auth token)"

A GitHub token reaches only the repos GitHub lets it read: Mergepatrol cannot tell which of its workspaces such a token belongs to. The tools marked Sign-in work across a workspace, so they need the sign-in. Each tool takes the repo as repo, owner/name, or the workspace as workspace, its installation ID, which get_session lists.

Each tool calls a route of the JSON API under /api, which the dashboard uses. A script can call the API itself with the same Authorization: Bearer header:

curl -H "Authorization: Bearer $(gh auth token)" \
  https://mergepatrol.ai/api/w/<installation ID>/repos/<owner>/<name>/pulls/<number>/status

Read a PR’s state from another app

An app that shows PRs, such as a PR list in an editor, reads what Mergepatrol knows of them from /api/v1, instead of working it out from labels and the config file. It authenticates as the API above does: Authorization: Bearer with the viewer’s GitHub token (OAuth, personal access token, or an App installation token) or a Mergepatrol session. GitHub decides what the token can read. A repo it cannot read is a 404, the same as a repo that does not exist. A repo it can read is a 200, also when Mergepatrol does not run there.

curl -H "Authorization: Bearer $(gh auth token)" \
  https://mergepatrol.ai/api/v1/repos/acme/widgets/pulls/42
curl -H "Authorization: Bearer $(gh auth token)" \
  "https://mergepatrol.ai/api/v1/repos/acme/widgets/pulls?numbers=42,43,44"

The second form reads up to 100 PRs of one repo, as { "pulls": [...] } in the order asked. Each PR reads:

{
  "repo": "acme/widgets",
  "number": 42,
  "url": "https://mergepatrol.ai/acme/widgets/pull/42",
  "mergepatrol": {
    "state": "on",
    "installed": true,
    "has_config": true,
    "override": null,
    "config_error": null
  },
  "queue": {
    "trunk": "main",
    "state": "held",
    "hold": {
      "reason": "review_required",
      "layer": null,
      "message": "waiting for a required review"
    },
    "priority": false,
    "position": 3,
    "stack": null,
    "batch_pr": null
  },
  "merged": null,
  "ejected": null
}

Every response has an ETag: send it back as If-None-Match for a 304 when nothing changed. Each caller, by its token, has 5,000 calls an hour, a 304 included, which x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used and x-ratelimit-reset (Unix seconds) report. Past the limit, a 429 has a retry-after, in seconds. So does a 503 when GitHub’s own rate limit is used up.

Docs

• Get started with Mergepatrol

  Sign in with GitHub, install the App, merge the setup PR, add a model key, and label a pull request to queue it.

• How the merge queue works

  What a queued PR needs, the agent that resolves conflicts and fixes failed checks, automatic review, branches, batches, stacks and PRs from forks.

• Configuration: .mergepatrol/mergepatrol.yml

  Every setting in a repo's .mergepatrol/mergepatrol.yml: the label, batch size, the agent's model, verify commands, CI fixes, extra branches and review bars.

• Pricing

  Mergepatrol is free on public repos. Private repos cost $15 a seat a month after a 14-day trial with no card. Self-hosting is free.

• Self-host Mergepatrol

  Run the open-source Mergepatrol yourself with Docker Compose, configure it, bring your own GitHub App, and isolate its jobs in gVisor sandboxes.