Connect your agent (MCP)

ProofGit exposes two read-only MCP (Model Context Protocol) servers, so an AI agent can query your repositories directly and get back the same trust and freshness signals a human sees in the web UI.

The two servers

Five repo-scoped tools, two fleet-scoped. The fleet server searches across every BNLRepo the caller can see in one query, or an explicit list of repositories you pass in.

What a tool call returns

This is the part that matters more than the tool list.

A search hit is an evidence bundle, not a snippet. It carries the matched .llm excerpt and the exact backing source lines read from the recorded commit, plus the freshness state, the model and provenance of the summary, and a jump-back URL into the web UI so a human can check the agent's work in one click.

Line spans are re-validated against the pinned blob before they are returned. A summary that points at line 240 of a file that is now 180 lines long does not quietly return the wrong lines — the mismatch is caught.

Results are packed to a token budget. Default limit is 8 results with a 6000-token budget; you can raise those to 25 and 32000 respectively. There is a summary_only mode if you want the excerpts without the backing source.

Authentication

A normal Gitea personal access token. Nothing bespoke.

Authorization: token <your-token>

Authorization: Bearer <your-token> is accepted too, which is what most MCP clients send by default.

• Repo-scoped needs code-read access to that repository.
• Fleet-scoped needs the repository token scope, and is limited to whatever its owner can already see.

Every tool only reads, so give the token read:repository scope and no write access. Mint one at Settings → Applications.

Access is enforced per request, on every read. The MCP servers do not widen what a token can reach; they are a different way to ask the same permission system the same question.

Wire protocol

Plain JSON-RPC 2.0 over HTTP POST. MCP protocol version 2025-06-18. Methods: initialize, ping, tools/list, tools/call; notifications are acknowledged. There is no SSE or streaming transport — a POST returns a response.

Request bodies are capped at 2 MiB.

Connecting Claude Code

The Connect your agent over MCP card on a repository's Sync Cockpit (/{owner}/{repo}/bnlgit) shows these snippets with your real endpoint already filled in. For a repository your-org/your-repo it reads:

claude mcp add --transport http proofgit-your-repo https://app.proofgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp --header "Authorization: Bearer YOUR_PROOFGIT_TOKEN"

Or, in a project's .mcp.json:

{
  "mcpServers": {
    "proofgit-your-repo": {
      "type": "http",
      "url": "https://app.proofgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PROOFGIT_TOKEN"
      }
    }
  }
}

The server name is proofgit- followed by the repository name, lower-cased, with every character other than a-z, 0-9, - and _ turned into - (and any leading or trailing - dropped), so My.Repo becomes proofgit-my-repo. Replace YOUR_PROOFGIT_TOKEN with your token. The same card has snippets for Codex and Cursor; they are also on Set up your agent.

For the fleet server, use https://app.proofgit.com/api/v1/bnlgit/mcp and the name proofgit-fleet instead; the fleet dashboard at /-/bnlgit shows the same card for it.

Checking it works without an agent

Every MCP server answers tools/list to an ordinary curl, which is the quickest way to confirm your token and URL before you go debugging your client's config:

curl -s https://app.proofgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp \
  -H "Authorization: token YOUR_PROOFGIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Choosing the right tool

• fetch_bnlgit_overview — the repository-level _OVERVIEW.llm. Cheap orientation; start an agent here rather than letting it list files.
• search_bnlgit_documentation — lexical search over the .llm summaries. Always available.
• search_bnlgit_code — exact search over your actual source, backed by git grep. Use it when you know the symbol.
• search_bnlgit_hybrid — vector-ranked retrieval over summary chunks, with backing source. Read Search before relying on this — it degrades to lexical results unless the repository has been configured for vector retrieval, and it tells you when it has done so.
• map_bnlgit_topology — the file-relationship graph built from every summary's structured related_files facts: which files a file references, which files reference it, and the repository's most-referenced files. Each edge carries the exact source spans in the declaring file plus a line-anchored link. Omit path to get only the most-referenced list; pass one to get that file's edges too.