Build on what Breno keeps.

Quick start

Three steps from nothing to a first answer. A token belongs to you in one workspace and sees exactly what you can see.

1. Create a token. In Breno open Connect AI, name the token, choose its scopes and expiry, and copy it. It starts with sirmx_mcp_ and is shown once.
2. Send it as a bearer token. The same token works on the REST API and on the MCP endpoint. Revoke it and it stops at once.
3. Search, then ask. Search returns passages and calls no model. Ask returns an answer with citations.

export BRENO=https://<your-breno-host>/api/v1
export TOKEN=sirmx_mcp_…

# Search without generating an answer (scope: read)
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"query":"data retention policy"}' "$BRENO/search/query"

# Ask, with citations (scope: ask)
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"question":"What did we decide about the Q3 launch?"}' "$BRENO/search/ask"

Authentication

Every request carries a personal token as a bearer token. A token has one or more scopes, chosen when it is created, and a call outside them returns 403 INSUFFICIENT_SCOPE.

Authorization: Bearer sirmx_mcp_…

Everything else (deleting, sharing, members, settings, token management) refuses a token with 403 SESSION_REQUIRED, so a leaked token cannot administer your workspace.

Search

POST /search/query returns ranked passages and calls no model, so it costs no coins. Filters narrow retrieval before ranking, so you get the best passages within the filter.

{
  "query": "data retention policy",
  "filters": {
    "source_providers": ["notion"],
    "date_from": "2026-01-01"
  }
}

Ask

POST /search/ask answers from your own material, with numbered citations. When the evidence is not there, insufficient_evidence is true and the answer says so. Asking spends coins; a workspace with none returns 402.

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"question":"What is our refund policy?"}' "$BRENO/search/ask" \
  | jq '.data | {answer, confidence, sources: [.evidence[] | {title, url: .source.url}]}'

GET /search/ask/stream returns the same answer as server-sent events: chunk events as it is written, then one done event.

Capture and edit

These need the write scope; each is recorded in the audit log with the token’s id. Send an Idempotency-Key on upload and capture, so a retry after a timeout cannot create two items.

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://example.com/article","visibility":"workspace"}' \
  "$BRENO/documents/capture"

Capture returns 202 with a document_id, a job_id and duplicate: when it is true the link was already captured. With a token you can edit only notes your account created.

Export

Your knowledge can always leave. Small sets come back at once; everything, or more than 500 items, runs as a background job you download when it finishes. The archive is Markdown, JSONL, the original files and checksums, and you can read it without Breno.

# up to 500 items, synchronously (scope: export)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -o breno-export.zip "$BRENO/knowledge/export/zip"

The format is documented member by member in Export format.

MCP server

Any MCP client can search, read, ask, export and capture under the same access rule as the app. The server is Streamable HTTP at /mcp on your Breno host; give your client the URL and the token.

{
  "url": "https://<your-breno-host>/mcp",
  "headers": { "Authorization": "Bearer sirmx_mcp_…" }
}

A client that can only start a local program uses the CLI bridge instead:

{
  "mcpServers": {
    "breno": {
      "command": "brainers",
      "args": ["serve", "mcp"],
      "env": { "BRENO_MCP_TOKEN": "sirmx_mcp_…" }
    }
  }
}

The nine tools

For a plain lookup use search then fetch: neither spends coins.

SDKs and CLI

Go and TypeScript clients cover the public API, with paging helpers and typed errors. The CLI’s serve mcp bridges stdio clients to your workspace. They live in the Breno repository and are not published to a package registry, so check the repository for how to add them to your project.

import { BrenoClient, RateLimitError } from '@brainers/sdk-ts';

const breno = new BrenoClient({
  baseUrl: 'https://<your-breno-host>',
  token: process.env.BRENO_TOKEN!,
});

for await (const doc of breno.iterateDocuments({ owner: 'me' })) console.log(doc.title);

await breno.captureNote('Standup 8 Oct', '- shipped the REST API');

Without an SDK the API is plain HTTP and JSON, so any language works.

Errors and limits

Responses use one envelope: { "success": true, "data": … } or { "success": false, "error": { "code", "message" } }.

Limits are 120 requests a minute per token and 300 per IP address for token traffic. Page instead of polling, back off on 429 and 5xx with a little jitter, and prefer search to ask for lookups.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Reference

The full contract is the OpenAPI document, and a test fails if the router, the token allowlist and the spec disagree. Stuck on something? Use the Ask Breno button at the bottom right, or write to us.

• API overviewBase URL, the seventeen operations, idempotency
• AuthenticationTokens, scopes, how they end
• Search and askFilters, fields, streaming
• ErrorsEvery code and what it means
• MCP serverProtocol, tools, resources
• Export formatThe archive, member by member
• All documentationGuides, concepts and reference