Versioning and compatibility

Downstream MCP servers sit behind Agentsyx upstream connectors and chat hosts that cache tools/list, resource URIs, and sometimes prompt catalogs. Treat everything those surfaces publish as a compatibility contract: breaking it without a coordinated migration produces failed tool calls, blank widgets, or stale prompts until caches refresh and mappings are updated.

What counts as breaking

Change	Typical impact
Rename or remove a tool `name`	Upstream tool mapping points at the old name; models may still emit it.
Remove or rename a required argument, or narrow a type / enum	Existing prompts and automations send the old shape; validation fails.
Change semantics of an argument or response (same name, different meaning)	Silent data corruption or wrong behavior—worse than a hard error.
Change or drop a resource URI used in `tools/list` / `resources/read` `_meta`	Hosts may load the wrong UI or nothing. See MCP App (widgets) metadata.
Change meaningful `_meta` keys or CSP-related fields hosts rely on	Embedding or `callServerTool` flows can break without obvious JSON-RPC errors.
Remove a prompt that upstream or docs still reference	Hosts that list prompts show gaps or errors for that id.

Usually non-breaking when done carefully: new optional tool arguments, new tools, new resources (without removing old URIs), clearer descriptions, and additive resources/read _meta that hosts ignore if unknown.

Tool and schema contracts

Treat name + inputSchema (and stable output shape if clients depend on it) as the public API for the upstream mapper, the model, and any integrations.
Prefer additive evolution: optional fields, new tools, or a new tool name (searchV2) alongside the old one during migration—then unmap and retire the old tool in Creator after traffic has moved.
If you must break a required field, ship a replacement tool (or versioned name), update documentation and prompts, remap upstream in Agentsyx, and only then remove the old definition.

MCP Apps: resources, `_meta`, and widgets

Stable resource URIs and consistent _meta between tools/list, tools/call results, and resources/read matter as much as tool names. Plan URI and _meta changes with the same discipline as tool renames. For protocol detail, see MCP server metadata and MCP App (widgets) metadata.

Deprecating tools and prompts

Introduce the replacement (new tool name or schema) and expose it from the downstream server.
In Agentsyx Creator, map the new upstream tool to the new downstream implementation; migrate any Parameter Tagging to the new parameter names if applicable.
Update internal docs, system prompts, and Zapier / n8n / Make automations that hard-code the old tool or argument names.
Remove the old tool (or old prompt) from tools/list / prompts/list only after no production upstream mapping and no critical callers still depend on it. Until then, the old tool can return a clear error message pointing operators at the replacement.

Server metadata and deployments

Bump serverInfo.version (or your SDK’s equivalent) when you ship behavior or schema changes you need to correlate with support tickets and logs.
Keep a short changelog or release note for connector operators: what changed, whether Creator remapping is required, and whether hosts should refresh tool lists.

Multi-connector setups

When backend, MCP App, and integration connectors are separate, version them independently but document cross-dependencies (for example: widget bundle version N expects tool loadItems shape from connector B). A change on one side may require a coordinated deploy and upstream mapping check. See Multi-connector architecture.

Quick checklist before a breaking release

New tool or additive schema only? Ship and document.
Renaming / removing? Add replacement, remap upstream, migrate callers, then remove old.
Widget / URI / _meta change? Verify resources/read and host embedding still work.
serverInfo.version and operator-facing notes updated?

Integration platforms Troubleshooting