Connect your agent (MCP)

BNLGit 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.

Both are Pro features. Every account on the hosted service runs on a Pro instance, so if you are on the hosted service, you have them.

The two servers

Four 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.

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

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

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

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

For the fleet server, use https://app.bnlgit.com/api/v1/bnlgit/mcp instead.

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.bnlgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp \
  -H "Authorization: token YOUR_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.