BHG Infra

API and MCP

The two ways software talks to Infra, and how each authenticates.

The MCP server

The supported way for agents and scripts to use Infra is the MCP server at /api/mcp on the Infra app.

  • Transport: Streamable HTTP, JSON responses, POST only. The server is stateless: one request per call, no batches.
  • Server name: bhg-edge. Tool calls show in clients as mcp__bhg-edge__<tool>.
  • Auth: Authorization: Bearer edge_sk_… (an Infra key), or the sign-in connector for Claude.
  • A browser session cookie is refused: the MCP server is for agents, not pages.
  • Each tool binds to the same HTTP route the web app uses, with the same role, page and ownership checks.

See Connecting agents, Keys and connectors and the tool reference.

The HTTP API

The web app's own routes live under /api, grouped by area (for example /api/projects, /api/engagements, /api/dle, /api/knowledge-containers). They are built for the app and change with it. Prefer the MCP tools, which are documented, versioned with the server and guarded for agents.

An Infra key also works on the HTTP routes the MCP tools bind to. Some actions are refused to every key on purpose, whatever its scopes:

  • applying or approving project changes through the browser-only paths,
  • signing a SOW or BRD, or attaching their documents (person_only),
  • direct edits of approved project state (key_write_forbidden): stage a change instead.

Scopes

ScopeAllows
readLook up anything you can see. Every key has it.
writeState-changing requests outside the knowledge surfaces.
entity:writeCreate, edit and archive knowledge on an engagement and its projects, and stage project changes.
kb:stagePropose knowledge-base pages for review.
kb:publishPublish knowledge-base pages. Admins only.

A key can be limited to one engagement. It is then refused on every other engagement, on reads as well as writes.

Errors

Refusals before a tool runs are HTTP errors (401 no or bad credential, 403 missing scope, 404 for client accounts, 429 over the hourly budget with Retry-After). Refusals by the route are tool results with a code. See Tool reference.

Idempotent writes

Write tools accept an idempotencyKey. Retrying with the same key returns the stored result instead of writing twice, to the same credential only.

On this page