How do you keep an MCP server and a CLI up to date when the API changes?

When a system offers an API, MCP server, and CLI, an API change can break the other two without anyone noticing. The user is the first to feel it.

First, the terminology: the API is the interface your system provides so other programs can communicate with it. The MCP server (the connector AI assistants use) and the CLI (the command-line version used in the terminal) are two ways to use that same interface.

Add a simple rule to AGENTS.md (the instruction file coding agents read when they open a project): when the API changes, check the MCP server and CLI and make any necessary updates.

The API is the foundation these interfaces depend on. Changing the foundation and forgetting what was built on top of it creates an organization and maintenance problem.

A release is only complete when its connected interfaces have been updated too.

Why everything gets out of sync

Each interface is usually written at a different time, sometimes by different people. The API gets a new field, a name changes, or a parameter becomes required. The MCP server and CLI stay on the old version.

The result is an AI assistant calling a function that no longer exists, or a terminal command returning an unexplained error. It’s not a lack of technical skill; a step in the process is missing.

A single source of truth

It helps to describe the API in a formal file, such as an OpenAPI specification (a standard document that lists each route, field, and response). Some MCP and CLI code can then be generated or checked automatically.

Even without code generation, this file becomes the reference the coding agent checks to see what changed.

Clear instructions for the agent

In AGENTS.md, specific rules work better. Instead of asking it to keep everything up to date, say which folders to check, which tests to run, and what to record in the change history.

That way, when you ask the agent to change the API, it knows the task includes the other interfaces too and doesn’t stop halfway.

A test that blocks the release

The strongest safeguard is an automated test that calls the API through MCP and the CLI and checks that the responses match. If they don’t, the release doesn’t go out.

That makes the rule a barrier in the process instead of something that depends on memory.

1. Describe the API in a specification file such as OpenAPI, and keep it with the code.
2. Write the list of MCP and CLI folders to check for every change in AGENTS.md.
3. Create a short test that calls the main functions through all three interfaces.
4. Make that test mandatory before publishing a version.
5. Record what changed in the API and interfaces in the change history.
6. Notify users when a change requires them to update the MCP or CLI.

• Leaving the rule vague in AGENTS.md: the agent takes the shortest path and skips steps.
• Testing only the API: the problem usually appears in the layers above it.
• Removing a field without warning: users on an older version break without knowing why.

• Add a rule to AGENTS.md.
• The API is the foundation; MCP and CLI sit on top.
• A release isn't complete until everything is updated.

• CourseMCP — Model Context Protocol from the ground upFrom the concept to building your own MCP server.
• Projectinema-agent-runtimeA ladder of options: API, MCP, CLI, or screen, and when to use each.
• Projectfaxina-agentesA single, organized AGENTS.md with the rules the agent follows.

Some of these materials are in Portuguese.