In short
fyrr reader serveexposes three read-only tools:search,fetchandlist_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.
search
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.
| Argument | Meaning |
|---|---|
query | 1–4096 characters. Omit it to list by updated_at (then order must be updated_at). |
queries | 2–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. |
limit | 1–75 documents, default 50. With queries, per query, default and maximum 20. |
output | metadata, excerpt (default) or content: what text each hit carries. |
order | relevance (default) or updated_at. |
text_hits | 0–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_chars | 1–1200: caps the excerpt length. |
sources, source_types, projects, authors | Exact-match filters, 1–64 values of 1–512 characters each. An unknown value gives an empty result. |
updated_after, updated_before | RFC 3339 instants; exclusive bounds. |
attributes | 1–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. |
exclude | 1–100 { source_id, root_id } pairs to leave out. |
deadline_ms | 1–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.
| Code | Retryable | Meaning |
|---|---|---|
invalid_argument | no | Input outside the schema or its limits; never clamped. |
authorization_unavailable | yes | Policy or identity missing, expired or malformed, or the caller exceeds the per-user token limit. |
storage_unavailable | yes | Storage could not be read. |
incompatible_index | no | The published index does not match this reader. |
deadline_exceeded | no | The request deadline passed. |
cancelled | no | The request was cancelled. |
stale_cursor | no | The cursor is expired, belongs to another subject or its content version changed. |
busy | yes | The namespace concurrency cap, queue or per-call work budget is exhausted. |
rate_limited | yes | A 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:
| Field | Meaning |
|---|---|
publication_id, content_version, committed_at | The publication the request was pinned to. |
degraded | Lanes that did not contribute: dense (no query embedding), rerank; lexical is reserved. |
hidden_sources | Up 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_version | The reader served an older pin than the live head allows (per-request mode). |
omitted_bytes | Bytes clipped from the response. |
telemetry | cache (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.