BOS Service · Public API contract · Version 1

Stream authorized source results

bos/source-results/v1 is an optional MCP delivery extension. It delivers source pages as they become available and finishes with one self-contained tool response. This page specifies the existing wire contract as of October 8, 2026. BOS Service owns the contract; clients choose adoption independently.

1. Discover the extension

Connect through the existing authenticated MCP connection. For supported 2025-era clients, inspect the initialize response. Stateless clients inspect server/discover. Both advertise the following object under result.capabilities.experimental; follow contractUri to this public document. Use the actual URI returned by your server.

{
  "bos/source-results/v1": {
    "pageSize": 100,
    "maxConcurrentSources": 8,
    "contractUri": "https://dfsm.ai/apps/bos/source-results-v1.html"
  }
}

pageSize bounds the records in each event page; maxConcurrentSources bounds concurrent source reads. These are advertised service limits. Version 1 accepts an empty opt-in object and provides no client setting for either limit. Initialization stores no streaming preference: each tool invocation negotiates independently.

2. Request streaming

POST a JSON-RPC tools/call request with a non-null string or integer id to the authenticated MCP endpoint used for discovery. Send Content-Type: application/json and Accept: application/json, text/event-stream. Set an object at params._meta["io.modelcontextprotocol/clientCapabilities"].experimental["bos/source-results/v1"]. Both the request-local opt-in and an Accept media type of text/event-stream are required. A Boolean opt-in does not negotiate this extension.

The following is an envelope template for the platform endpoint /mcp/apps/bos/platform. Replace DISCOVERED_CONTEXT_HANDLE, DISCOVERED_READ_TOOL_NAME, and the business arguments object with the current authorized discovery results and the selected operation's input schema. Preserve its existing execution and approval requirements.

{
  "jsonrpc": "2.0",
  "id": "search-1",
  "method": "tools/call",
  "params": {
    "name": "bos_execute",
    "arguments": {
      "context_handle": "DISCOVERED_CONTEXT_HANDLE",
      "tool_name": "DISCOVERED_READ_TOOL_NAME",
      "arguments": {}
    },
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {
        "experimental": {
          "bos/source-results/v1": {}
        }
      }
    }
  }
}

Use the same metadata placement for directly discovered tools. Keep the negotiated MCP protocol version and its normal headers and request metadata. For 2025-era clients, initialize alone is insufficient to opt in. If either streaming signal is absent, the invocation returns the existing JSON response. Authentication and request validation failures retain their existing HTTP/JSON-RPC semantics; inspect HTTP status and Content-Type before parsing.

For the stateless 2026-07-28 protocol, send MCP-Protocol-Version: 2026-07-28, Mcp-Method: tools/call, and Mcp-Name: bos_execute for the template above (or the actual direct tool name). Preserve params._meta["io.modelcontextprotocol/protocolVersion"]: "2026-07-28" and params._meta["io.modelcontextprotocol/clientInfo"] alongside the clientCapabilities object. Header and body versions must match; use the currently discovered supported version.

A negotiated response has Content-Type: text/event-stream (possibly with a charset), Cache-Control: no-cache, and X-Accel-Buffering: no. Federation read operations emit source notifications. Other tools may emit only the final response. This extension grants no additional access.

3. Parse the event stream

Every JSON payload arrives in an SSE event: message frame, terminated by a blank line. The JSON-RPC notification method is notifications/bos/source_result. Dispatch on the JSON method inside data. The SSE event name remains message. Comments such as : bos/source-results/v1 and : keepalive carry no result or completion information.

This synthetic sequence shows one record page and its source completion. The context labels and handle are illustrative.

event: message
data: {"jsonrpc":"2.0","method":"notifications/bos/source_result","params":{"requestId":"search-1","sequence":1,"pageIndex":1,"source":{"source_type":"example","source_identity":"demo-source"},"records":[{"record_ref":"bos:person:demo-1","display_name":"Example Person","email":null,"phone":null,"lifecycle":null,"sources":[{"source_type":"example","source_identity":"demo-source","external_id":"demo-1","record_type":"person","observed_at":"2026-10-08T12:00:00Z","capabilities":["read"],"version":null}],"identity_match":null,"attributes":{}}],"status":"page","context":{"context_handle":"DISCOVERED_CONTEXT_HANDLE","organization_name":"Example Organization","application_name":"Example Application","installation_name":"Example Installation","role_label":"Example Role","is_default":true}}}

event: message
data: {"jsonrpc":"2.0","method":"notifications/bos/source_result","params":{"requestId":"search-1","sequence":2,"pageIndex":1,"source":{"source_type":"example","source_identity":"demo-source"},"records":[],"status":"complete","context":{"context_handle":"DISCOVERED_CONTEXT_HANDLE","organization_name":"Example Organization","application_name":"Example Application","installation_name":"Example Installation","role_label":"Example Role","is_default":true}}}

Each FederatedRecord contains record_ref, optional nullable display_name, email, phone, lifecycle, identity_match, an attributes object, and a nonempty sources array. Each provenance entry carries source_type, source_identity, external_id, record_type, observed_at, supported capabilities, and optional nullable version. Preserve the returned records and provenance using the selected operation's public result contract.

4. Track sequencing and paging

Sources execute concurrently, so notifications from different sources can interleave. Arrival order does not promise a source order. Each source's page indexes begin at 1 and advance by one for each page; exactly one complete or error follows that source's pages during normal completion. An empty successful source emits complete with pageIndex: 0 and records: [].

Page size is a bound. A short page does not signal completion. Delivery pages may split provider pages, or chunk a fully buffered provider result; first-page timing and provider-native pagination depend on the adapter. Records are validated against the authorized source before publication. Event pages apply source-local federation within each chunk. Identity merging across pages and sources is authoritative in the final result, so provisional counts and record identities may change there.

sequence and pageIndex describe this invocation only. They are not cursors, SSE replay IDs, or resume tokens. There is no durable job, subscription, or resumable session associated with this extension.

5. Consume terminal statuses and the final response

A source error carries records: [] and one of source_timeout, source_identity_mismatch, provider_authorization_required, rate_limited, or source_unavailable. Provider exceptions and credentials are excluded. An error can follow previously delivered pages; retain them as partial observations until the final result arrives.

event: message
data: {"jsonrpc":"2.0","method":"notifications/bos/source_result","params":{"requestId":"search-1","sequence":3,"pageIndex":0,"source":{"source_type":"example","source_identity":"other-demo-source"},"records":[],"status":"error","error":{"code":"source_timeout"},"context":{"context_handle":"DISCOVERED_CONTEXT_HANDLE","organization_name":"Example Organization","application_name":"Example Application","installation_name":"Example Installation","role_label":"Example Role","is_default":true}}}

One final event: message follows all source terminal statuses on a normally completed read. Its JSON-RPC body has the original id and either result or a top-level error, and no source-notification method. The result is the existing self-contained CallToolResult: clients can consume it independently of earlier pages. The final federated result includes all successfully delivered records, merged using the operation's normal identity rules.

For direct federated read tools, records are under result.structuredContent.result and metadata under result.structuredContent.metadata. For bos_execute, its identity envelope wraps that operation result: records are under result.structuredContent.result.result, metadata under result.structuredContent.result.metadata, and the public context under result.structuredContent.context and result._meta["bos/context"]. Success has metadata.completeness: "complete" and isError: false. Any source failure sets metadata.completeness: "partial", isError: true, and metadata.source_errors, whose entries contain source and error.code. An all-source failure remains partial even with zero records. A complete empty result has complete metadata and no source failures. Transport or runtime errors before source execution may produce a final error response with no source notifications.

This final bos_execute frame completes the synthetic sequence above: one source succeeded and the other timed out. It repeats the successful record in the authoritative result. A stateless response also adds resultType: "complete"; that indicates invocation completion and can coexist with partial read metadata.

event: message
data: {"jsonrpc":"2.0","id":"search-1","result":{"content":[{"type":"text","text":"{\"contract_version\": \"bos-identity-mcp/v2\", \"context\": {\"context_handle\": \"DISCOVERED_CONTEXT_HANDLE\", \"organization_name\": \"Example Organization\", \"application_name\": \"Example Application\", \"installation_name\": \"Example Installation\", \"role_label\": \"Example Role\", \"is_default\": true}, \"result\": {\"result\": [{\"record_ref\": \"bos:person:demo-1\", \"display_name\": \"Example Person\", \"email\": null, \"phone\": null, \"lifecycle\": null, \"sources\": [{\"source_type\": \"example\", \"source_identity\": \"demo-source\", \"external_id\": \"demo-1\", \"record_type\": \"person\", \"observed_at\": \"2026-10-08T12:00:00Z\", \"capabilities\": [\"read\"], \"version\": null}], \"identity_match\": null, \"attributes\": {}}], \"metadata\": {\"retrieval_mode\": \"live_provider\", \"cache_baseline_applied\": false, \"source_delta_applied\": false, \"completeness\": \"partial\", \"result_count\": 1, \"observed_at\": \"2026-10-08T12:00:00+00:00\", \"provenance\": [{\"source_type\": \"example\", \"source_identity\": \"demo-source\", \"observed_at\": \"2026-10-08T12:00:00+00:00\"}], \"source_errors\": [{\"source\": {\"source_type\": \"example\", \"source_identity\": \"other-demo-source\"}, \"error\": {\"code\": \"source_timeout\"}}]}}}"}],"structuredContent":{"contract_version":"bos-identity-mcp/v2","context":{"context_handle":"DISCOVERED_CONTEXT_HANDLE","organization_name":"Example Organization","application_name":"Example Application","installation_name":"Example Installation","role_label":"Example Role","is_default":true},"result":{"result":[{"record_ref":"bos:person:demo-1","display_name":"Example Person","email":null,"phone":null,"lifecycle":null,"sources":[{"source_type":"example","source_identity":"demo-source","external_id":"demo-1","record_type":"person","observed_at":"2026-10-08T12:00:00Z","capabilities":["read"],"version":null}],"identity_match":null,"attributes":{}}],"metadata":{"retrieval_mode":"live_provider","cache_baseline_applied":false,"source_delta_applied":false,"completeness":"partial","result_count":1,"observed_at":"2026-10-08T12:00:00+00:00","provenance":[{"source_type":"example","source_identity":"demo-source","observed_at":"2026-10-08T12:00:00+00:00"}],"source_errors":[{"source":{"source_type":"example","source_identity":"other-demo-source"},"error":{"code":"source_timeout"}}]}}},"isError":true,"_meta":{"bos/context":{"context_handle":"DISCOVERED_CONTEXT_HANDLE","organization_name":"Example Organization","application_name":"Example Application","installation_name":"Example Installation","role_label":"Example Role","is_default":true}}}}

Operation deadlines remain in force. A source timeout cancels that source while retaining records successfully delivered by it and other sources. Disconnect cancels outstanding work. An EOF or connection failure before the matching final response means the invocation has no confirmed terminal result, even if every observed source appeared complete. Apply the selected operation's normal recovery and retry rules.

6. First-request consumer checklist

1. Find bos/source-results/v1 in authenticated discovery and read its contractUri.
2. Discover a permitted read tool and its complete arguments; preserve the existing BOS context and credentials.
3. Send the request-local empty capability object and the Accept header above with a non-null JSON-RPC id.
4. Parse SSE incrementally across network chunks and blank-line frame boundaries; ignore comments and join multiple data lines using the normal SSE rules.
5. For source notifications, verify requestId, track global sequence, and track pages and terminal status by the complete source pair. Present pages as provisional authorized observations.
6. Wait for the matching final JSON-RPC response. Use it as the authoritative result and inspect isError, completeness, and source errors. Replace or reconcile provisional pages with the final records to avoid double-counting.

Use a streaming HTTP client capable of POST and authentication. Browser EventSource issues GET and cannot send this JSON request body. A client that opts out continues to use the existing JSON delivery contract.