Set up your agent

This page is the short, practical version of Connect your agent (MCP): what to paste into each client, and how to check it worked.

The snippets below are the ones the forge itself shows. Open a paired repository's Sync Cockpit at /{owner}/{repo}/bnlgit and expand Connect your agent over MCP: the card there has your real endpoint already filled in, with a copy button beside each snippet. Here they are for a repository your-org/your-repo.

1. Mint a token

Create an access token at Settings → Applications with read:repository scope. Every tool only reads, so do not give it write access. Treat the token like a password: anything holding it can read what you can read.

The snippets carry a placeholder, YOUR_PROOFGIT_TOKEN, where the token goes; Codex reads it from the PROOFGIT_TOKEN environment variable instead. 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.

2. Add the server to your client

Claude Code

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 add it to the 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"
      }
    }
  }
}

If you commit .mcp.json, do not commit a real token in it.

Codex

codex mcp add proofgit-your-repo --url https://app.proofgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp --bearer-token-env-var PROOFGIT_TOKEN

Or add it to ~/.codex/config.toml:

[mcp_servers.proofgit-your-repo]
url = "https://app.proofgit.com/api/v1/repos/your-org/your-repo/bnlgit/mcp"
bearer_token_env_var = "PROOFGIT_TOKEN"

Either way, set PROOFGIT_TOKEN to your token in the shell you start Codex from. Codex then sends it as a bearer token, and the token never sits in Codex's config file.

Cursor

Add it to .cursor/mcp.json:

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

3. Or search every repository at once

The fleet endpoint answers across every paired repository the token's owner can read. Its server name is proofgit-fleet, and the fleet dashboard at /-/bnlgit shows its card:

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

codex mcp add proofgit-fleet --url https://app.proofgit.com/api/v1/bnlgit/mcp --bearer-token-env-var PROOFGIT_TOKEN

For .mcp.json, config.toml or Cursor, take the snippets above and swap in proofgit-fleet and https://app.proofgit.com/api/v1/bnlgit/mcp. The fleet server's tools are list_bnlgit_repos and search_bnlgit_hybrid; see the two servers.

4. Check it from a terminal

Before you debug a client's config, ask the server directly. With PROOFGIT_TOKEN set:

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

A working setup returns a JSON-RPC result listing the five repo-scoped tools: fetch_bnlgit_overview, search_bnlgit_documentation, search_bnlgit_code, search_bnlgit_hybrid and map_bnlgit_topology. An error here is a token, scope or URL problem, not a client problem.

5. Tell the agent when to use it

It helps to tell the agent, in the repository's own instructions, when to use the server. Lines like these work in an AGENTS.md (read by Codex and other agents) or a CLAUDE.md (read by Claude Code); change the server name to yours:

## Code context (ProofGit)
- This repository is paired on ProofGit. Its MCP server is `proofgit-your-repo`.
- Before reading files to answer a question about how the code works, call
  `fetch_bnlgit_overview` once for orientation.
- Use `search_bnlgit_code` when you know a symbol or string, and
  `search_bnlgit_documentation` or `search_bnlgit_hybrid` when you know a concept.
- Before changing a file, call `map_bnlgit_topology` with its path to see what
  references it.
- Every result cites source lines at a recorded commit. Check its freshness:
  treat a stale or unverified result as a lead, and re-read the cited lines
  before you edit anything.

What each tool does, and why the results carry their own evidence, is in Choosing the right tool.

For agents reading these docs

A plain-text index of this documentation, one line per page, is at /llms.txt.