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 asmcp__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
| Scope | Allows |
|---|---|
read | Look up anything you can see. Every key has it. |
write | State-changing requests outside the knowledge surfaces. |
entity:write | Create, edit and archive knowledge on an engagement and its projects, and stage project changes. |
kb:stage | Propose knowledge-base pages for review. |
kb:publish | Publish 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.