Tool naming and source sync
Two settings on a deployed MCP server decide what your tools are called and whether that set changes when your spec does. Both are quiet until the day they are not, and on that day they are breaking changes for everyone already connected. Worth understanding before you touch either.
How tools get their names
A naming strategy turns each OpenAPI operation into a tool name. There are two, and the choice shows up in how confidently an agent picks the right one.
operation-id
Built from the operation's operationId. The default for new servers, and the more readable option for a model choosing between tools.
method-path
Built from the HTTP method and path. Works even when a spec defines no operation IDs at all.
Either way the result is lower_snake_case and capped at 64 characters, the limit MCP clients apply to tool names.
Changing the strategy renames every tool on the server. Any agent already wired to the old names stops finding them, and it will not tell you why. It simply behaves as though the tools no longer exist. Treat a strategy change the way you would treat renaming endpoints in a public API: as a breaking change your consumers need warning about.
Servers created before this setting existed are pinned to method-path. That pin is deliberate: their tool names were already in production, and adopting the new default would have renamed them silently. Moving an older server to operation-id means opting into that rename. It does not happen on its own.
What happens when your spec grows
When you add an endpoint to the underlying collection and redeploy, follow source decides whether agents get it automatically.
- Off, the default: a redeploy keeps exactly the operations you previously selected. A new endpoint stays invisible to agents until you tick it explicitly.
- On: operations added to the spec after the first deploy are exposed automatically.
Leave it off when your MCP surface is a deliberate subset of your API and every addition should be a decision. Turn it on when the server is meant to mirror the whole spec and the review step is only friction.
Pointing at a different upstream
A base URL override sends tool calls somewhere other than the server URL declared in your spec. It is the clean way to run a server against staging without editing the spec to get there and editing it back afterwards.
Where to go next
On this page
- Tool naming and source sync