Skip to content

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.

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
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.

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.

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 inputSchema lists a required property;
  • a marked tool whose execution.taskSupport is "required".

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.

server.py
from fastmcp import FastMCP
from 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.

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 ready calls, in a racy order: one install from the install itself and one resume from 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 install call at all, because there was no server to call when the install returned. Its first ready carries "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.

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.

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.

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:

  • removing records the intent to release, and never destroys. Let a separate process act on that record after a grace period. A later ready withdraws the intent, so a stray removing followed by normal use costs nothing.
  • ready only ever converges toward “installed”. Calling it twice, or from the wrong caller, must leave the same state as calling it once.
  • reason is 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 removing calls live, since it is already converging recorded intent against the vendor.

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.

  • A host that does not implement the extension sees ordinary tools with an unfamiliar _meta key 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/discover carries 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 in initialize as 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).

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.

  • 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 ready set up.
  • Notifications: telling the host about facts you learn later, which is the other half of a server that does work between calls.