Skip to content

Extensions

A server written to the Model Context Protocol specification works on NimbleBrain without modification. The extensions in this section are additions to the protocol for things the specification does not cover yet: they travel in MCP messages, are negotiated between the server and the host, and could be implemented by any host. A server that ignores all of them still works; one that uses them can do more.

Two other kinds of ai.nimblebrain/* contract are documented elsewhere, because different parties agree to them:

  • Host integration: what a server asks NimbleBrain to grant it (pages, a settings section, admin-only tools, webhooks, a notification outbox), declared in its catalog entry and reviewed by the operator. It never travels in an MCP message.
  • App bridge extensions: methods an app’s view uses inside the shell, beside the MCP Apps specification’s own.

Each line is one capability, and each links to its page. The last column names the extension that carries it.

Capability What your server gets Carried by
Lifecycle Told when it is installed into a workspace and just before it is removed, so it can set up and release per-workspace state it holds elsewhere ai.nimblebrain/lifecycle
Facets Counts of work waiting on someone, shown on the workspace overview ai.nimblebrain/facets
Host resources Workspace files read by URI, instead of pasted into a tool argument ai.nimblebrain/host-resources
Resource arguments Resources served in the workspace, such as another server’s records, named by URI in your tool’s arguments and delivered with the call as their server returned them ai.nimblebrain/resource-arguments
Notification events The title, body and level the host renders an outbox event with (the outbox itself is declared in the catalog) ai.nimblebrain/notification

Reserved keys are the other half of the namespace: ai.nimblebrain/* keys only the host sets, which a server must not send.

The specification describes a conversation between one client and one server. NimbleBrain is a long-running, multi-workspace host: it runs agents with no human present, keeps files that belong to a workspace, renders apps inside a shell, and routes events to people. Some of what a server needs from that host has no place in the specification yet.

For those needs, the host defines an extension. It does this only when all three of these hold:

  1. The specification has no mechanism for it. When the specification (or the MCP Apps extension) covers a need, the host implements the specification’s version and does not add its own.
  2. Something on the other side of the wire reads it. An extension is a contract between two parties, so it ships with a named consumer. A signal the host sends only to itself is not an extension, and is not listed as one. Such keys are reserved instead.
  3. Ignoring it is safe. Every extension has a defined fallback, which is simply the behavior without it.

The rules below apply to every extension, so a developer who learns one can predict the rest.

One namespace. Every extension method, capability, and _meta key is named under ai.nimblebrain/, the reversed form of a domain NimbleBrain owns. This is the naming convention the specification sets for third-party keys, so nothing here can collide with the specification or another vendor.

Negotiated, never assumed. A server learns which extensions the host offers from the client capabilities the host sends: in the initialize handshake on a 2025-era connection, and in each request’s _meta envelope on 2026-07-28. Server-facing capabilities arrive in capabilities.extensions, and the host claims one only on the eras where it serves it. The bridge extensions arrive in hostCapabilities.experimental, because the MCP Apps handshake type has no extensions field yet. Code that uses an extension checks for it first and falls back when it is absent. That way the same server runs on NimbleBrain and on any other host.

Specification shapes, renamed. Where an extension does something the specification already has a shape for, it reuses that shape exactly. For example, ai.nimblebrain/resources/read takes a standard ReadResourceRequest and returns a standard ReadResourceResult, and the error codes are the specification’s. If the specification adopts the capability, moving to it means dropping the prefix from the method name, with no schema migration.

A key the host acts on is host-owned. A _meta key a server sets is a claim made by that server. When the host’s own behavior depends on a key, such as its loop guard or its skill delivery, the host sets that key itself and removes any copy a server sends. Those keys are listed under reserved keys, so a server author knows that setting one has no effect. Every other _meta key a server sets passes through untouched.

The host tells a server nothing it would not need. A request carries what the specification defines and what a negotiated extension adds. It never says how a call was triggered or whether anyone is watching. A server that behaves differently when no one is looking is exactly the server that information would help.

Each entry names the parties the extension connects, its identifier, and why it exists.

Extension Direction Why it exists
ai.nimblebrain/facets Server → host (capability and marked resources), on both eras A server holds work that needs someone, and the workspace overview should say how much without a model or a side channel. The server lists each count as a resource with a _meta marker and answers resources/read with { "count": n }; the host renders <count> <title>.
ai.nimblebrain/lifecycle Server → host (capability and marked tools), then host → server (tools/call), on both eras A server that holds state elsewhere for a workspace needs to know when it was installed and when it is about to be removed, and no MCP message says either. The server marks one tool per event with a _meta marker; the host calls it at that moment and withholds it from every other caller.
ai.nimblebrain/host-resources Host → server (capability), then server → host (requests), on 2025-era connections only MCP resources flow from server to client only. A server that needs a file the user gave the workspace would otherwise have it pasted into a tool argument by the model: slow, expensive in tokens, and capped by the context window. With this extension, the server reads the file from the host by URI.
ai.nimblebrain/resource-arguments Host → server (capability), server → host (marked tools), then host → server (contents in the tools/call _meta), on both eras A tool that needs a resource served in its workspace would otherwise have the model copy it into an argument. The motivating case is a server that must check a record another server owns: without this it calls that server directly, coupling the two, or trusts the model’s copy. The tool marks which arguments hold resource URIs and which schemes it accepts; before the call, the host reads each URI from the server in the same workspace that serves it and sends the contents with the call.
Extension Direction Why it exists
ai.nimblebrain/notification Server → host, on an outbox event A server that learns something nobody asked for (a reply arrived, a job finished) publishes it as an event on its outbox resource. The host renders and routes these events to people. This block gives the host the title, body, and level to render them with. The event itself follows the shape of the MCP triggers-and-events proposal.

Skills are not a resource convention. A server publishes them through the MCP Skills Extension (skills/list), and a skill:// resource the server does not list is an ordinary resource.