MCP server

Breno's Model Context Protocol server: the endpoint, protocol versions, authentication, the nine tools and what each returns, and documents as resources.

Report a problem with this page

The Breno MCP server lets any MCP client search, read, ask, export and capture into your workspace, under the same access rule as the app.

Endpoint and protocol#

The server is Streamable HTTP, at /mcp on your Breno host (also reachable at /api/v1/mcp/external). 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 a session. A client ends a session with DELETE.
Replies are JSON or server-sent events, and batching follows the protocol version.
Tool failures come back as results with isError.
The Origin header is checked against an allow-list.
A request without a valid token gets 401 with a WWW-Authenticate header that points at the resource metadata.

Authentication#

Send a personal token as a bearer token. See Tokens. Clients that add a server by URL can use OAuth 2.1 with dynamic client registration; the tokens that flow issues work on MCP only.

Tools#

Nine tools, all under the shared read rule.

Tool	Scope	What it does
`search`	`read`	Hybrid keyword and semantic retrieval over documents, notes, links, meetings and synced sources. Returns ranked results, one per item, each with the best-matching passage. No answer is generated and no coins are spent.
`fetch`	`read`	Reads one item in full by id. Returns its text, address and metadata, including provenance (source, author, dates). When `metadata.truncated` is true, call again with `offset` set to `metadata.next_offset`.
`list_documents`	`read`	Lists items newest first, filtered by source, space or date, with paging (page size 1 to 100).
`read_document`	`read`	Reads an item by document id: its summary, when there is one, and its extracted content. Prefer `fetch`.
`list_sources`	`read`	Lists 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`	Answers a question with confidence and citations (`document_id`, `title`, `url`, `text`). Spends workspace coins.
`export_knowledge`	`export`	Exports what this token can read in the portable v2 format. Small sets are returned inline with their text; large sets return an export job to poll. Audit-logged.
`capture_note`	`write`	Saves a note (Markdown or plain text), owned by the token's owner. Returns `duplicate: true`, and the existing item, when identical content was already saved.
`capture_url`	`write`	Saves 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 recorded in the 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.

Try it#

Initialize a session, then list the tools

curl -s https://<your-breno-host>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

The response carries an Mcp-Session-Id header; send it on later requests such as tools/list.

What has been tested#

The endpoint is covered by scripted-client tests for each scope and by a live session (discovery, initialize, capture_note, search, fetch, end session). It has not been run through the MCP Inspector. See Connect a client.