Developers
Use what Breno keeps from any client that speaks the Model Context Protocol: search it, read it, ask it, capture into it and export it, all under the same access rule as the app.
Endpoint and protocol
The server is Streamable HTTP, at /mcp on your Breno host. It speaks protocol version 2025-06-18 and negotiates 2025-03-26 and 2024-11-05. Sessions are identified by a signed Mcp-Session-Id, so any replica can serve them, and a client ends a session with DELETE. Replies are JSON or server-sent events, tool failures come back as results with isError, and the Origin header is checked against an allow-list.
Authentication
Send a personal token as a bearer token. Create one in Settings, then Connect AI; it starts with sirmx_mcp_, is shown once, and carries the scopes you choose (read, ask, export, write). It sees exactly what you can see and stops at once when revoked, expired, or when you leave the workspace. A request without a valid token gets 401 with a WWW-Authenticate header pointing at the resource metadata.
For clients that add a server by URL, the server also supports OAuth 2.1 with dynamic client registration. Tokens it issues work on MCP only, and the REST API refuses them.
Tools
Nine tools, all under the shared read rule: a confidential item is invisible to a token without the grant, and nothing here decides access with a model.
| Tool | Scope | What it does |
|---|---|---|
search | read | Hybrid keyword and semantic retrieval over documents, notes, links, meetings and synced sources. Results are ranked, one per item, with the best-matching passage. No answer is generated and no coins are spent. |
fetch | read | Read one item in full by id. Returns its text, url and metadata, including provenance (source, author, dates). When metadata.truncated is true, call again with offset set to metadata.next_offset. |
list_documents | read | List items newest first, filtered by source, space or date, with paging (page size 1 to 100). |
read_document | read | Read an item by document id: its summary, when there is one, and its extracted content. Prefer fetch. |
list_sources | read | List connected sources with sync state, last sync, last error, consecutive failures and how many of each source's items this token can read. |
ask_knowledge | ask | Ask a question in natural language and get an answer with confidence and citations. Spends workspace coins, so use search and fetch for plain lookups. |
export_knowledge | export | Export what this token can read in the portable v2 format. Small sets come back inline with their text; large sets return an export job to poll. Audit-logged. |
capture_note | write | Save a note (Markdown or plain text), owned by the token's owner. Reports duplicate=true, and returns the existing item, when identical content was already saved. |
capture_url | write | Save a web page, video or file link; Breno fetches and reads it in the background. Reports duplicates the same way. |
Viewers cannot capture. Capture and export calls are written to the workspace audit log with the token’s id.
Resources
Items are also exposed as resources at breno://document/{id}, as Markdown, so a client that browses resources can read them without calling a tool.
Connecting a client
Most clients take a server URL and an Authorization header; the exact file and field names differ from client to client, so follow your client’s own instructions and give it these two values:
{
"url": "https://<your-breno-host>/mcp",
"headers": { "Authorization": "Bearer sirmx_mcp_…" }
}A client that only speaks stdio can use the CLI (apps/cli), whose serve mcp command bridges stdio to the endpoint with a scoped token.
What has been tested
capture_note, search, fetch, end session). The OAuth flow for adding Breno to Claude.ai and ChatGPT by URL is built and tested the same way, but has not yet been exercised against the live services, which needs a public HTTPS deployment. The MCP Inspector has not been run against it, and redirects with a custom scheme (such as cursor://) are not accepted. Until those are done, treat the bearer-token route as the supported one.