Capability Lifecycle
How clients migrate from old MCP capabilities to replacements
The gateway can replace an MCP capability when a safer, clearer, or more precise alternative exists. Replacements use a lifecycle that lets existing workflows keep running while clients migrate.
States
| State | What clients see | What clients should do |
|---|---|---|
| Active | No lifecycle metadata | Call normally |
| Deprecated | Descriptor and result notice | Show the replacement and migrate before the sunset time |
| Removed | Structured replacement error | Stop retrying the old capability |
Metadata
Deprecated and removed capabilities use the metadata key
lovelace.ai/capability-deprecation.
{
"code": "capability_deprecated",
"capabilityType": "tool",
"name": "old_tool",
"state": "deprecated",
"replacement": "new_tool",
"sunsetAt": "2026-08-01T00:00:00.000Z",
"documentationUrl": "https://developers.uselovelace.com/mcp/capability-lifecycle",
"reason": "Use the workspace-scoped replacement."
}
For deprecated tools, the gateway includes this object in both the tools/list
descriptor and successful tools/call result metadata. For removed tools, the
gateway returns isError: true and includes the same object in
structuredContent and result metadata with code: "capability_removed".
Client behavior
Clients should branch on metadata and structured content, not on display text. During a sunset window, surface the replacement to users and update saved workflows. After removal, suppress automatic retries for the old capability and call the replacement directly.
The human-readable error text can change without changing the lifecycle contract.