API-Style Lifecycle Tools for MCP Servers

Jul 9, 2026 · Stève Sfartz

Most MCP servers start small: a local connector, a few tools, a README, and a client configuration. That is often good enough to get an assistant connected and demonstrate quick value.

Once servers become a critical integration layer between AI agents and enterprise systems, new challenges arise:

What exactly does that MCP server expose today?
What changed since the previous release?
Did we add, remove, or change tools?
Are its tools designed in a consistent way?
How can we document this server efficiently and accurately?

These are not new questions. API teams have been solving them for years using formalized definitions, linting, documentation generation, changelog automation, and controlled lifecycle.

MCP Toolkit brings that same API-style lifecycle thinking to MCP servers.

It helps you inspect, describe, compare, document, and govern MCP servers across releases.

Why MCP servers need lifecycle tooling

The Model Context Protocol is built around dynamic discovery: a client connects to a server and discovers its tools, resources, prompts, and transports at runtime. That works well for agents, which need to know a server’s capabilities the moment they connect.

But runtime discovery only shows what a server exposes at a specific moment. Teams operating an MCP server also need a durable artifact they can store in Git, review in pull requests, compare across releases, feed into documentation, and use in compliance or governance workflows.

In other words, runtime discovery helps clients understand a server in the moment. Lifecycle tooling helps humans and automation understand how that server evolves over time. That is the space MCP Toolkit explores.

The core idea: capture capabilities as a description

MCP Toolkit starts with a simple idea:

Capture the capabilities of a specific MCP server version into a static, machine-readable description.

We call the format the MCP Description format, and a concrete YAML or JSON file using it an MCP Description document — often referred to as an mcpdesc file. The distinction matters:

the MCP Description format defines the structure and semantics;
the MCP Description specifications define the formal versions of that format;
MCP Description documents are the actual YAML or JSON files describing a given MCP server version.

The approach is inspired by OpenAPI, and designed for MCP servers. OpenAPI does not replace an API implementation — it describes it. In the same way, an MCP Description document provides a stable artifact describing what a given server version offers: server metadata, supported transports, tools, resources, prompts, input and output schemas, security expectations, and documentation metadata.

Once that artifact exists, you can build a lifecycle around it.

What the MCP Toolkit can do today

The MCP Toolkit focuses on practical workflows for people building, documenting, or governing MCP servers. There are two entry points that we recommend starting with:

mcpcontract, a CLI for extracting, validating, documenting, and comparing MCP server releases;
the MCP Description Editor, a browser-based tool for authoring, validating, previewing, and exporting MCP Description documents.

Dump a live MCP server

The first useful workflow is to connect to a live MCP server and capture its capabilities.

The command looks like this:

mcpcontract dump \
  --transport streamable-http \
  --url "https://your-mcp-server.example.com/mcp" \
  --output server.yaml

The output is an MCP Description document in YAML or JSON. Instead of only relying on runtime discovery, you now have a versioned artifact that captures what the server exposed at a specific point in time.

This is the key transition:

Live MCP server
      │
      ▼
`mcpcontract dump`
      │
      ▼
server.mcpdesc.yaml

Compare two server versions

Once you have documents for two revisions of a server, you can compare them. The command looks like this:

mcpcontract diff \
  --from previous.yaml \
  --to current.yaml \
  --output diff.json

The result is a structural diff.json that can help identify:

added tools;
removed tools;
renamed tools;
schema changes;
input or output changes;
documentation changes;
potentially breaking changes.

This is where MCP server development starts to look more like API lifecycle management. A server is not just “available” — it evolves, and each release may introduce changes that affect agents, users, documentation, or integrations. A structured diff makes those changes easy to understand and review.

Generate changelogs

A diff is useful for engineering review; a changelog is useful for communication. The changelog command turns a structural diff into release notes:

mcpcontract changelog \
  --diff diff.json \
  --format release \
  --output CHANGELOG.md

If you also want to flag breaking changes, run mcpcontract breaking on the diff first — or use mcpcontract compare to run the whole diff → breaking analysis → changelog pipeline in a single step.

The goal is to turn structural changes into release information that humans can read and CI automation can act on.

Generate reference documentation

MCP Description documents can also be used as input for documentation generation.

The command looks like this:

mcpcontract document server.yaml \
  --template reference-documentation \
  --output docs.md

This does not remove the need for human review, but it gives documentation teams better starting material. Instead of manually reconstructing what a server exposes, they generate documentation from the same artifact used for review, comparison, and lifecycle management.

That creates a more reliable chain:

MCP server capabilities
      │
      ▼
MCP Description document
      │
      ▼
Diff and changelog
      │
      ▼
Generated documentation
      │
      ▼
Human review and publication

Edit and preview in the browser

The second entry point to the MCP Toolkit is the MCP Description Editor — similar in spirit to Swagger Editor, but for MCP Description documents. It lets you:

open or paste an MCP Description document;
validate it;
preview the rendered documentation;
inspect structured cards for tools and schemas;
export YAML, JSON, or Markdown.

This is useful when you want to understand the format, edit a document manually, or review how a server description will render. It is also a good starting point if you are not ready to run the CLI yet: load an example, inspect the structure, and see how MCP server capabilities are represented.

You can try it here: editor.mcptoolkit.org.

Why this matters for MCP governance and quality

MCP server descriptions are not only useful for documentation — they also create a foundation for quality and governance workflows. Once a server has a structured description, you can address these challenges:

Are tool names consistent?
Are tool descriptions clear enough for both humans and agents?
Are input schemas precise?
Are output schemas documented?
Are transports and security expectations explicit?
Are breaking changes detected before release?
Is the documentation accurate, aligned with the actual capabilities of the latest release?

These questions matter because MCP servers are consumed by AI agents. A vague tool description does not only confuse a developer reading the docs; it does affect how an agent selects or uses that tool. High quality MCP servers need to be designed beyond runtime correctness — with clarity, consistency, and lifecycle as top of mind.

A practical workflow

A simple workflow with MCP Toolkit could look like this:

1. Build or update your MCP server
2. Run `mcpcontract dump`
3. Validate the generated MCP Description document
4. Compare it with the previous version (diff → breaking analysis → changelog)
5. Review major or breaking changes
6. Generate or update documentation
7. Publish the server and documentation together

In practice:

# Capture the current server capabilities
mcpcontract dump \
  --transport streamable-http \
  --url "https://your-mcp-server.example.com/mcp" \
  --output current.yaml

# Validate the generated document
mcpcontract validate current.yaml

# Compare with the previous version — runs diff → breaking → changelog in one step
mcpcontract compare \
  --from previous.yaml \
  --to current.yaml \
  --suggest-version \
  --output CHANGELOG.md

# Generate documentation
mcpcontract document current.yaml \
  --template reference-documentation \
  --output docs.md

These commands are intentionally close to the way API teams already work with API descriptions, lifecycle artifacts and tools such as spectral and oasdiff.

A format to discuss with the community

MCP Description format emerged from practical engineering needs at Cisco — inspecting, comparing, documenting, and governing MCP servers — and it works for the workflows we have tested. We think it’s now time to engage with the broader community.

Does the MCP ecosystem need a shared static description format for server capabilities?

We believe the answer may be yes, especially as MCP servers spread into enterprise, platform, documentation, and compliance workflows. That discussion should happen openly, with the MCP community and the teams evolving the protocol.

MCP already provides the runtime foundation. MCP Toolkit explores what lifecycle tooling can look like around it — and we would love your help shaping it.

Try MCP Toolkit

If you build or maintain an MCP server, the easiest place to start is mcpcontract: dump your server capabilities into an MCP Description document, then compare the result across versions. To explore the format visually, open the MCP Description Editor at editor.mcptoolkit.org. All the projects live in Cisco Open.

We are looking for feedback from MCP server builders, API governance teams, documentation engineers, and MCP users alike. Join the conversation on GitHub Discussions and tell us what works, what is missing, and how you would use MCP Description in your own lifecycle workflows.

Stève Sfartz — Creator and Lead Maintainer of the MCP Toolkit