Reference

MCP tools

Three tools. Your agent works out the rest.

In short

  • fyrr reader serve exposes three read-only tools: search, fetch and list_filters.
  • This page lists their arguments, the error codes, the response metadata and the transport rules for stdio and Streamable HTTP.
  • Read it when you connect an agent or another MCP client to fyrr.

fixtures/mcp/tools-list.json is the exact tools/list response (names, descriptions, input and output schemas, annotations); fixtures/mcp/examples/ holds example requests and responses and fixtures/mcp/error-codes.json the closed list of error codes. All three are generated from the Rust types and compared in CI. Terms such as publication and pin are defined in How fyrr works.

Every tool definition carries the MCP contract version in _meta["fyrr/schema_version"]; every successful response carries it in metadata.schema_version (currently 3.0). Returned text is data, not instructions.

Transport

Stdio: the client completes initialize and notifications/initialized before tool calls. The preferred protocol revision is 2025-11-25; 2025-06-18 and 2025-03-26 are negotiated. Frames over 1 MiB close the transport; unparsable JSON frames are ignored. The stdio subject is identity.stdio_user.

Streamable HTTP ([reader.http]): the same tools at /mcp, authenticated per request by an OIDC access token; see HTTP login and users.

Unknown tools and arguments outside the schema return a tool error without ending the process. Byte limits (x-maxUtf8Bytes) are enforced on every string before admission, next to the character limits.

Searches the authorized corpus with lexical and dense retrieval, fused and grouped per document. Only documents the caller may read are returned; an empty result is not an error. Scores only order results.

ArgumentMeaning
query1–4096 characters. Omit it to list by updated_at (then order must be updated_at).
queries2–16 query texts of 1–4096 characters each instead of query. limit is then per query; hits are interleaved by rank and query index and deduplicated across queries, up to namespace.retrieval.max_documents.
limit1–75 documents, default 50. With queries, per query, default and maximum 20.
outputmetadata, excerpt (default) or content: what text each hit carries.
orderrelevance (default) or updated_at.
text_hits0–75, and at most the effective limit; a larger value, or any value with output: "metadata", is invalid_argument. Only the top text_hits hits carry text, the rest metadata only. With queries, per query before deduplication.
excerpt_chars1–1200: caps the excerpt length.
sources, source_types, projects, authorsExact-match filters, 1–64 values of 1–512 characters each. An unknown value gives an empty result.
updated_after, updated_beforeRFC 3339 instants; exclusive bounds.
attributes1–16 connector attributes as { key, values } (a key of 1–128 characters, 1–64 values of 1–384 characters each): equality or IN within one key, AND across keys.
exclude1–100 { source_id, root_id } pairs to leave out.
deadline_ms1–300000; default 10 s.

Each hit has source_id, root_id, record_id, revision, source_uri, source_type, title, author, team, project, status, labels, created_at, updated_at, score, an excerpt (text, start, end in codepoints of that record) or content, and with queries a query_index. An excerpt is a passage of up to 1200 codepoints whose record_id, revision and offsets can be passed to fetch as a window. truncated reports hits and text dropped by reader.max_response_bytes.

fetch

Fetches documents by exact uri (1–4096 characters), by source_id with root_id (1–512 characters each), or by documents (1–5 ordered { source_id, root_id } lookups, each with an optional window), and continues with cursor (1–16384 characters). deadline_ms is 1–300000 as for search. Unknown and denied documents both give an empty result, which is not an error.

A page holds at most 5 documents, 32 records and 64 KiB of text. Records come in section and chunk order, also across pages. Clipping preserves UTF-8, reports omitted_bytes, and the cursor resumes inside a partially served record. Each document carries the same metadata as a hit plus connector_map (connector-specific metadata) and records (record_id, revision, text).

A window (record_id, revision, start, and exactly one of end or context) returns one span of one record. A top-level window also needs source_id and root_id. Offsets count codepoints; context is 0–65536. If the record's text changed, the response sets document_changed and returns no span. An unknown or denied record returns an ordinary empty result, even for an out-of-range offset.

Cursors are authenticated (HMAC-SHA256 under the identity hashing key), bound to the namespace, the subject, and the pinned content version, and expire after 15 minutes. Tampering, another subject or namespace, expiry or a changed content version yields stale_cursor. Policy and identity changes alone do not invalidate a cursor: its page is filtered under the new admission.

list_filters

Returns the projects, source_types and authors the caller may read, at most 64 values each, with readable document counts (one per source_id/root_id). More than 64 distinct values gives status: "too_many" with no values. Nulls are absent and values sort bytewise. The scan inspects at most reader.filter_count_max_rows authorized rows and returns busy rather than partial counts above it. Its only argument is deadline_ms, 1–300000 as for search.

Errors

A failed tool call returns isError: true with a structured error (schemas/mcp-tool-error.schema.json) that holds only code, message and retryable. The table includes the HTTP-only rate_limited code.

CodeRetryableMeaning
invalid_argumentnoInput outside the schema or its limits; never clamped.
authorization_unavailableyesPolicy or identity missing, expired or malformed, or the caller exceeds the per-user token limit.
storage_unavailableyesStorage could not be read.
incompatible_indexnoThe published index does not match this reader.
deadline_exceedednoThe request deadline passed.
cancellednoThe request was cancelled.
stale_cursornoThe cursor is expired, belongs to another subject or its content version changed.
busyyesThe namespace concurrency cap, queue or per-call work budget is exhausted.
rate_limitedyesA per-user or per-group request limit was reached.

HTTP boundary refusals (authentication, rate, size and connection limits) are HTTP statuses with a body {"error":"<code>"}, not tool results. rate_limited appears only as HTTP 429. Error messages never contain document text, identities or query text.

Response metadata

Every successful tool response carries metadata:

FieldMeaning
publication_id, content_version, committed_atThe publication the request was pinned to.
degradedLanes that did not contribute: dense (no query embedding), rerank; lexical is reserved.
hidden_sourcesUp to 64 source IDs hidden because their permission or membership freshness expired, among those with at least one row the caller could otherwise read.
stale_versionThe reader served an older pin than the live head allows (per-request mode).
omitted_bytesBytes clipped from the response.
telemetrycache (hot, warm; cold is reserved), queue_wait_ms, per-stage microseconds in stage_us, S3 requests and bytes per stage, candidate counts, unindexed_rows_scanned, filter_rows_scanned, routing_strategy, routing_fallback, rerank_us.

Search responses omit stage_us and rerank_us and keep queue_wait_ms at zero to avoid exposing shared query-embedding cache activity. For fetch and filter-list responses, stage timers are inclusive of their children and must not be summed; total starts when the complete input frame arrives and ends before protocol output. Telemetry contains no user data.

Concurrency, deadlines and cancellation

Authorization is checked before retrieval and again before any result or error leaves the process (how).

reader.concurrency (default 8) requests execute at once, each on an independent prepared reader; the waiting queue has the same bound, and beyond it the response is busy. Requests may finish out of arrival order.

Deadlines start when the complete input frame arrives (HTTP: at arrival, including authentication), default to 10 s and cannot exceed 300 s. Queue expiry performs no storage work. notifications/cancelled with params.requestId drops executing work; the final authorization check keeps at most one second of grace, and failing it refuses the response. Cancelling one request does not affect others.

Edit this page on GitHub ↗