Local MCP transport

The optional server installation exposes the opened workspace through the pinned MCP SDK. python -m tychora.interfaces.http.server WORKSPACE serves Streamable HTTP at http://127.0.0.1:PORT/mcp/ alongside the versioned HTTP API. The owner publishes the current loopback authority and bearer credential in its private .runtime/endpoint.json; clients must keep that record private and send Authorization: Bearer …. The same numeric loopback Host, optional matching Origin, request body limit, token grant, and optional X-Tychora-Scope rules used by the HTTP API apply to MCP. The service is one installation principal with narrower token grants, not an independent identity provider.

An embedding process can call await tychora.interfaces.mcp.server.serve_stdio(workspace) to own stdio and the workspace. Its stdout carries MCP protocol frames only; diagnostics go to stderr. This owner also starts the protected loopback control endpoint and publishes the private runtime record so authorized sibling connect_local(workspace) clients delegate to it. tychora --workspace WORKSPACE serve --stdio is the CLI entry point. There is no separate MCP owner beside an already open owner.

The server registers five tools. discover accepts the public DiscoverRequest subjects (kinds, facets, relations, profiles, languages, sources, settings, runs, models), with cursor and limit. search accepts a public QueryRequest in request (including the documented { "question": "…" } shorthand), or replay_run_id; optional render selects markdown@1, agent@1, or hierarchical-evidence@1. inspect accepts the public InspectRequest or SourceCoverageRequest for bounded source revisions, extractions, and channels. add_sources accepts action: add with a public SourceInput mapping, or action: sync with a source ID; both return the shared durable source-job handle. manage_job supports scoped list, get, cancel, and retry. Its write actions independently check write capability and durable job authorization; they do not grant workspace management. A reader sees discovery, search, inspection, and read-only job operations; add_sources is omitted from its tool list and direct write calls still fail. Agents should use the tool schemas returned by MCP discovery rather than hard-coded kind IDs or metadata fields.

inspect also accepts subject: "source_selections" with source_id, revision_id, extraction_id, limit and optional cursor. It lists bounded source-native image and context selectors with retained hashes. Submit an explicit vision selection through the existing add_sources source mapping; MCP uses the same canonical request and current upload policy as Python and HTTP.

For example, an MCP client can call discover with { "request": { "subject": "kinds" } }, then call search with { "request": { "question": "verification", "modalities": ["lexical"] } }. A successful search has a typed QueryResult in structuredContent. The default response has no duplicate text block. Selecting render adds one text block. inspect returns its typed inspection or coverage record under structuredContent.result; coverage pages use the same scope-bound cursors and limits as the public source service. Source mapping shorthand resolves collection_id: "default" only when the actual grant includes that registered collection. File, folder, and repository paths must stay within configured ingest roots.

Resource templates are tychora://schemas/{name}, tychora://kinds/{id}, tychora://evidence/{id}, and tychora://assets/{id}. They resolve registered definitions or currently readable records. Assets return only registered payload bytes and are limited to 16 MiB; no resource template reads an arbitrary filesystem path. Unknown IDs and out-of-scope records fail through sanitized errors. The default metadata-only query history cannot replay absent retained request bodies and returns REPLAY_UNAVAILABLE.

Search fitting measures the installed SDK's actual UTF-8 structuredContent JSON fragment, plus the exact UTF-8 bytes of any selected rendered text block, with the configured token counter. The first declared render target is mcp-structured-json@2.2.0; optional text keeps its renderer-specific target. This invocation-bound serializer also enters the query projection/cache identity, so HTTP canonical JSON and MCP results cannot reuse incompatible cached payloads. The result's content totals cover those declared representations. Every serialized MCP CallToolResult is separately capped at 4 MiB; an oversized original revision inspection returns OUTPUT_BUDGET_EXCEEDED as a small error result. Protocol framing bytes are not included in the result's content totals. Other transport responses retain their own serialization targets. Idle initialized HTTP sessions hold no service admission; each active MCP tool or resource operation pins the current service binding. During shutdown the host closes MCP sessions before draining accepted source jobs and closing owner storage.