Lifecycle
A server that keeps anything outside itself for a workspace (a tenancy at a vendor, a storage bucket, a sending domain, a webhook registration) needs to know two moments: when it was installed into a workspace, and when it is about to be removed. Nothing in MCP tells you either. A tool call arrives when someone asks for something, and an install or an uninstall is not that.
Lifecycle tells you both. It is an
MCP extension,
ai.nimblebrain/lifecycle, built on the core Tools primitive. It adds no
method. You advertise the extension, mark one of your tools per event with a
_meta key, and the host calls that tool with an ordinary tools/call.
Nothing goes in your catalog entry. Any MCP SDK can do it; in Python the
Server SDK does it with one decorator per event, shown
under Complete examples.
What it enables
Section titled “What it enables”Per-workspace state at a third party, created on install and released on uninstall, with no operator script. Without it, someone has to provision the vendor side by hand before the connector works, and remember to clean it up after. With it, installing the connector is the whole setup, and removing it starts the teardown.
Lifecycle is one of three capabilities that together let a server own a vendor integration end to end:
| Capability | What it does for the integration | |
|---|---|---|
| 1 | Lifecycle | Creates the vendor-side resource when the connector is installed, and releases it when the connector is removed |
| 2 | Inbound webhooks | Receives the vendor’s events about that resource |
| 3 | Notifications | Tells the workspace what happened: the domain went active, a reply landed |
The two events
Section titled “The two events”| Event | Meaning | Called | Arguments |
|---|---|---|---|
ready |
The host has made your server available to the workspace, and the connection is up | The first time your server is reachable in a workspace, and on every later reconnect until one call succeeds | { "reason": "install" | "resume" } if your handler declares reason, otherwise {} |
removing |
The host is about to stop using your server for the workspace for good | Immediately before the connector is uninstalled, while your server is still reachable | {} |
reason answers exactly one question: was this the user’s install?
"install" means it was. "resume" is every other cause: a host restart, a
reconnect, a re-auth, your server redeployed at the same URL. They are one value
because you have nothing to do differently with them and the host frequently
cannot tell them apart.
A server that ignores reason entirely is still correct. What it loses is the
ability to tell the user’s act from the system’s state, which is mostly useful
for what you say, not for what you write.
The extension never names the workspace. Your server knows which workspace a call is for from the identity the connection already carries, the same identity its other tools serve.
1. Advertise the extension
Section titled “1. Advertise the extension”Put the extension in the extensions map of your server capabilities, with an
empty settings object:
{ "capabilities": { "tools": {}, "extensions": { "ai.nimblebrain/lifecycle": {} } }}Where that map travels depends on the protocol revision the connection
negotiated: on 2026-07-28 it is in the server/discover result, and on a
2025-era connection it is in the initialize result. The host reads it from
wherever the connection carries it, and negotiates 2026-07-28 with any server
that offers it. A marked tool on a server that did not advertise the extension
on that connection is an ordinary tool, and the host never calls it as a
handler.
The host advertises ai.nimblebrain/lifecycle in its own
client capabilities
on both eras, so your server can tell whether it will be called.
2. Mark one tool per event
Section titled “2. Mark one tool per event”A handler is an ordinary tool in your tools/list result, carrying the
extension identifier as a _meta key:
{ "name": "workspace_ready", "description": "Records that this workspace has the connector installed.", "inputSchema": { "type": "object", "properties": { "reason": { "type": "string", "enum": ["install", "resume"] } } }, "_meta": { "ai.nimblebrain/lifecycle": { "event": "ready" } }}| Field | Rule |
|---|---|
_meta["ai.nimblebrain/lifecycle"] |
Required. An object. The host tolerates fields it does not know. |
…event |
Required. "ready" or "removing". The host ignores a marker whose event it does not recognise, and reports it as an install warning. |
inputSchema |
Must not list any required property. A ready handler may declare an optional reason. |
execution.taskSupport |
Must not be "required". "optional" is allowed: the host calls every handler inline, without task augmentation. |
Mark one tool per event, or none: each event is optional on its own. The marker is the only signal. The host never identifies a handler by its name or its description, so name the tools whatever you like.
The host treats these as undeclared, calls nothing for them, and reports each as a warning on the install:
- an event marked on more than one tool (the host does not choose one);
- a marked tool whose
inputSchemalists arequiredproperty; - a marked tool whose
execution.taskSupportis"required".
Complete examples
Section titled “Complete examples”Each server advertises the extension and marks two handlers.
nimblebrain-server-sdk advertises the extension and marks the tool. It refuses, when the server is built, a handler that requires an argument or a second handler for one event, and registers each handler without task support.
from fastmcp import FastMCPfrom nimblebrain_server_sdk import CHANGES, add_lifecycle_extension
mcp = FastMCP("acme-outreach")lifecycle = add_lifecycle_extension(mcp)
@lifecycle.handler("ready", annotations=CHANGES)async def workspace_ready(reason: str | None = None) -> str: """Records that this workspace has the connector installed.""" state = await request_tenancy(current_workspace()) # an upsert if reason == "install": return "Setting up your sending workspace. It will be ready in a few seconds." return f"Sending workspace: {state}."
@lifecycle.handler("removing", annotations=CHANGES)async def workspace_removing() -> str: """Records that this workspace's tenancy should be released.""" await release_tenancy(current_workspace()) return "Releasing your sending workspace."A complete, tested server is in the Server SDK lifecycle guide.
Neither server needs anything beyond an MCP SDK.
TypeScript
import { McpServer } from "@modelcontextprotocol/server";import * as z from "zod";
const LIFECYCLE = "ai.nimblebrain/lifecycle";
export const server = new McpServer( { name: "acme-outreach", version: "1.0.0" }, { capabilities: { tools: {}, extensions: { [LIFECYCLE]: {} } } },);
server.registerTool( "workspace_ready", { description: "Records that this workspace has the connector installed.", inputSchema: z.object({ reason: z.enum(["install", "resume"]).optional() }), _meta: { [LIFECYCLE]: { event: "ready" } }, }, async ({ reason }) => { // Idempotent by construction: record that this workspace wants a tenancy, // and let your own reconciler converge it. Do not make the slow vendor // call here; the user is waiting on the install. const state = await requestTenancy(currentWorkspace()); // an upsert const text = reason === "install" ? "Setting up your sending workspace. It will be ready in a few seconds." : `Sending workspace: ${state}.`; return { content: [{ type: "text", text }] }; },);
server.registerTool( "workspace_removing", { description: "Records that this workspace's tenancy should be released.", _meta: { [LIFECYCLE]: { event: "removing" } }, }, async () => { // Mark it for release and return. The same reconciler does the vendor call. await releaseTenancy(currentWorkspace()); return { content: [{ type: "text", text: "Releasing your sending workspace." }] }; },);Python (FastMCP), without the Server SDK
from fastmcp import FastMCPfrom fastmcp.server.extensions import ServerExtension
LIFECYCLE = "ai.nimblebrain/lifecycle"
class Lifecycle(ServerExtension): """Advertises the extension. It serves no method of its own."""
identifier = LIFECYCLE
def settings(self) -> dict: return {}
mcp = FastMCP("acme-outreach")mcp.add_extension(Lifecycle())
@mcp.tool(meta={LIFECYCLE: {"event": "ready"}}, task=False)async def workspace_ready(reason: str | None = None) -> str: """Records that this workspace has the connector installed.""" state = await request_tenancy(current_workspace()) # an upsert if reason == "install": return "Setting up your sending workspace. It will be ready in a few seconds." return f"Sending workspace: {state}."
@mcp.tool(meta={LIFECYCLE: {"event": "removing"}}, task=False)async def workspace_removing() -> str: """Records that this workspace's tenancy should be released.""" await release_tenancy(current_workspace()) return "Releasing your sending workspace."request_tenancy and release_tenancy record intent, and nothing in them calls
the vendor. Privileged work
explains why.
Delivery: at least once, and twice on a fresh install
Section titled “Delivery: at least once, and twice on a fresh install”The contract is at least once per workspace per host process in which your connection comes up. Concretely:
- A fresh install of a connector that connects at once delivers two
readycalls, in a racy order: oneinstallfrom the install itself and oneresumefrom the connection coming up. This is intended, not a bug to work around. They are two different notifications, and collapsing them would mean telling a freshly installed connector"resume". - A connector whose connection comes up later (an interactive OAuth flow) gets
no
installcall at all, because there was no server to call when the install returned. Its firstreadycarries"resume". - After one call succeeds, later reconnects in the same host process do not call again.
So your handler must be idempotent. Write it as “make this true”, not as “do this once”: an upsert, not an insert.
removing is called before the host closes the connection and before it
discards the credentials it holds for the workspace, because after that there is
nothing to call. If the host no longer holds your handler when the removal
begins (the host restarted since your server last connected, say), it
reconnects to find it first. The uninstall waits for the call, and for
that reconnect, for at most a few seconds, then proceeds without it.
Return quickly. Both handlers are awaited: ready inside the install the
user is watching, removing inside the uninstall. Record the intent and let
your own background work converge it. A handler that waits on a vendor
round-trip makes the install feel broken and the uninstall feel stuck.
Failure semantics
Section titled “Failure semantics”An undeclared handler (marked twice, a required property, task support required) or an unknown event |
A warning on a successful install. The connector installs and works, and no call is made for that event. The host re-reads your handlers on every reconnect and every notifications/tools/list_changed, so fixing the server is enough: no reinstall. A ready call skipped for a rejected handler is made once the fixed handler is listed. A marker with an unknown event names no event the host can attribute, so a ready call it was meant for is not made again until the host restarts or the connector is reinstalled. |
ready fails or errors |
Never fails the install. Retried on the next reconnect, and on your next notifications/tools/list_changed. |
removing fails, errors, or cannot be reached |
Never fails the uninstall. The uninstall waits for the call for a few seconds and then proceeds without it. Not retried; the connector is gone. |
| Your server lists no tools yet | Not an error. The host waits for your tool list and calls then. |
A result with isError: true, a JSON-RPC error and a timeout are all failed
calls. Neither event has a retry queue. The events are the retry: another
reconnect, another install.
Only the host calls a handler
Section titled “Only the host calls a handler”A lifecycle event is a statement by the host: I installed you, I am removing
you. A call from anyone else would forge it. So the host withholds your marked
tools from everyone else: they are absent from every tool listing it gives a
model, in chat or at its MCP endpoint, and a call to
one from the agent, an app view, the API or another MCP client is refused with
the structured error host_only_tool, workspace admins included. Your other
tools are unaffected.
This applies to connectors installed in a workspace. A personal connector is neither called nor has its handlers withheld.
Your handler must be safe for any caller
Section titled “Your handler must be safe for any caller”The host withholds your handlers, but nothing else does. A host that does not implement this extension lists them as ordinary tools and may offer them to a model, and anyone who holds your server’s credential for a workspace can call them directly. So write each handler as if any of those callers could reach it:
removingrecords the intent to release, and never destroys. Let a separate process act on that record after a grace period. A laterreadywithdraws the intent, so a strayremovingfollowed by normal use costs nothing.readyonly ever converges toward “installed”. Calling it twice, or from the wrong caller, must leave the same state as calling it once.reasonis data, not authority. It says why the host called; it proves nothing. Never gate a privileged act on it.- Take the workspace from the connection’s identity, never from an argument. The host sends none, and your server must not accept one.
You may also leave your handlers out of tools/list for a client that did not
advertise the extension in its client capabilities, where the negotiated
revision lets you tell (on 2026-07-28, client capabilities arrive with each
request). You may additionally mark them with the MCP Apps
_meta.ui.visibility: ["app"], for hosts that honour it. Neither replaces the
rules above.
Privileged work: record it, act on it elsewhere
Section titled “Privileged work: record it, act on it elsewhere”Creating a tenancy or a domain usually needs a credential with broad power at the vendor. Keep that credential out of the handlers.
Record the request as ordinary state in ready, such as a row saying “this
workspace wants a tenancy”, and return. A separate process that holds the
privileged credential reads those rows and acts on them, and does the same for
the release rows removing writes.
- The handler stays fast: it writes a row, so the install is not waiting on a vendor round-trip.
- It stays idempotent: recording “wants a tenancy” twice is the same row, which is what at-least-once delivery needs.
- It stays unprivileged: the process serving tool calls never holds the credential that can create or destroy resources at the vendor, so a bug or a prompt-injected call on that path cannot reach it.
- The separate process is also where retries, the grace period before a
release, and the sweep for missed
removingcalls live, since it is already converging recorded intent against the vendor.
What the user sees
Section titled “What the user sees”ready’s text result becomes a notice on the install, shown beside the
“Installed …” confirmation. That is the one place a user waiting on setup you
started is told to wait, so write it for them:
Installed “Acme Outreach” in this workspace. Setting up your sending workspace. It will be ready in a few seconds.
Only the install call surfaces this way; a resume has nobody watching. The
host renders the text as text, never as markup, may truncate it, and never
passes it to a model as instruction. removing’s result is not shown; the
uninstall has its own confirmation.
Compatibility
Section titled “Compatibility”- A host that does not implement the extension sees ordinary tools with an
unfamiliar
_metakey and never calls them as handlers. It may offer them to a model, which is why your handlers must be safe for any caller. - A server that does not implement the extension advertises nothing, and the host calls nothing. Neither side rejects the other.
- A 2025-era connection to a server that advertises only in
server/discovercarries no extension, so no events are sent and no error is raised. A server that needs events from a host that speaks only 2025 must advertise ininitializeas well. - Your server must not depend on the events to be correct, because many hosts will never send them. Do per-workspace setup lazily on first use as well, or offer it as an explicit tool, and keep the sweep for releases that never arrived.
This is version 1 of the extension. A new event value, or new optional fields
in the marker or the settings object, keep the identifier; a host ignores what
it does not recognise. Removing an event, changing its meaning or its delivery
guarantee, or adding a required argument would ship under a new identifier
(ai.nimblebrain/lifecycle-v2).
Where pre_install and post_uninstall went
Section titled “Where pre_install and post_uninstall went”If you have written a Helm chart (pre-install … post-delete) or an npm
package (preinstall … postuninstall), you will look for the full matrix.
There isn’t one, and the reason is structural rather than a roadmap item.
The notification is a tool call on your own server. That single fact decides the set:
| Transition | Callable? | |
|---|---|---|
| not installed → installing | no | there is no server to call |
| installing → installed | no | the connector exists but its connection may not be up (interactive OAuth) |
| → running, or reconnected | yes | the first moment your server is reachable at all |
| running → disconnected | no | unreachability is the event |
| installed → uninstalling | yes, but only before teardown | after it there is nothing to call |
| uninstalling → gone | no | — |
Exactly two moments are reachable, and “was this the install?” is not a third:
it is a property of the first, which is what reason carries.
The rule that falls out:
Before a connector is reachable and after it is gone, extension is DECLARATIVE: the host acts on what it already knows. In between, extension is CALLABLE: the host calls your server.
So the “missing” events are not gaps, and some of them already ship. Install-time secret collection is the pre-install extension point, declared as what I need rather than as a call. Retiring your webhook registrations and deleting the secrets you declared are the post-uninstall ones, performed by the host off the connector’s own record.
Helm and npm carry the full matrix because the manager runs the hook in a
context it controls (a Job, a shell script) and never calls into the thing
being managed. Every system shaped like this one converges on two, with the same
asymmetry: Kubernetes lifecycle: { postStart, preStop }, VS Code
activate/deactivate, Chrome onInstalled/onSuspend.
Related
Section titled “Related”- Extensions: the rules every
ai.nimblebrain/*extension follows, and the registry. - Protocol support: the client capabilities the host advertises, on each era.
- Inbound webhooks: receiving the vendor’s events about
what
readyset up. - Notifications: telling the host about facts you learn later, which is the other half of a server that does work between calls.