Facets
A facet is a count a host shows without being asked: tickets blocked, drafts awaiting review. The protocol is the facets extension, ai.nimblebrain/facets. The SDK supplies the identifier, the marker and the read’s body.
from nimblebrain_server_sdk import ( FACETS_EXTENSION_ID, add_platform_extension, facet_count, facet_meta,)
add_platform_extension(mcp, FACETS_EXTENSION_ID) # 1. advertise the extension
@mcp.resource( # 2. list the facet as a resource "acme://facets/blocked", name="tickets-blocked", title="Tickets blocked", mime_type="application/json", meta=facet_meta("critical"),)async def tickets_blocked() -> str: return facet_count(await count_blocked()) # 3. answer the read with a countThe quickstart server has a facet in a complete file.
The rules
Section titled “The rules”- The marker is the contract. A host takes a facet from the
_metakeyfacet_metawrites, never from the URI’s shape. titleis the label, rendered after the number: “3 Tickets blocked”.- The level (
critical,warningorinfo) belongs to the facet, not to a reading.facet_metaraisesValueErrorfor any other value. - The read takes no arguments and counts at the source, for the caller’s identity.
facet_countrefuses anything but an integer of at least zero. A boolean or a float raises.- Only a
2026-07-28connection sees the declaration. On a 2025-era connection the marked resources are ordinary resources a host ignores.
Test it
Section titled “Test it”served_facets finds the marked resources the way a host does, checks each one’s title, MIME type and level, and reads each count:
from nimblebrain_server_sdk.testing import served_facets
assert await served_facets(mcp, "auto") == { "tickets-blocked": {"title": "Tickets blocked", "level": "critical", "count": 0}}Other platform extensions
Section titled “Other platform extensions”add_platform_extension(mcp, identifier, settings) advertises any ai.nimblebrain/* extension that adds no methods of its own. FastMCP refuses a registration once the server is serving, and a second registration of one identifier, so register at import.
A server with several views names the view that shows a kind of record on that record’s resource template:
from nimblebrain_server_sdk import record_view_meta
@mcp.resource("acme://boards/{board_id}", name="board", meta=record_view_meta("ui://acme/boards"))async def board(board_id: str) -> str: ...Related
Section titled “Related”- Facets extension: the protocol and what the host does
- Testing
- API reference