apigenie-mcp
apigenie-mcp (since 0.12.0) gives coding agents the checks of the CLI as tools of the
Model Context Protocol: lint, breaking changes, changelogs,
formatting, bundling and an outline of an API. It is installed next to apigenie by every archive
and package, npm and Homebrew. describe reads the file itself; the other tools run
apigenie --json for each call. lint, check_breaking_changes, changelog and format read
the apigenie.yaml that the command finds from the directory of the file.
(experimental, outside the 1.0 compatibility promise) MCP is still moving: tool names, arguments and results can change with it. Its
--helpsays so; it prints nothing when it starts, as the client reads its output.
Usage
apigenie-mcp [--allow-write] [--root DIR]... [--apigenie PATH] [--timeout SECONDS]
apigenie-mcp --version | --credits | --license [LIBRARY] | --license-list
You don’t run it yourself: the agent’s client starts it and talks to it on the standard input and
output. Add it to the client’s MCP settings, for example in .mcp.json at the root of a
repository for Claude Code:
{
"mcpServers": {
"api-genie": { "command": "apigenie-mcp", "args": [] }
}
}
Other clients take the same command and arguments in their own settings.
Options
| Option | Description |
|---|---|
--allow-write |
Let lint, format and bundle write files. |
--root DIR |
A directory the tools may work in, when the client gives no roots. Can be repeated; defaults to the current directory. |
--apigenie PATH |
The apigenie binary to run. Defaults to the one next to apigenie-mcp, else the one in PATH. |
--timeout SECONDS |
How long one run of apigenie may take (default 120). |
Exit status
| Status | Meaning |
|---|---|
| 0 | The client closed the standard input, which ends the session, or --help, --version, --credits, --license or --license-list printed its text. A tool that fails is a result of the call, not an exit status. |
| 2 | --timeout isn’t a positive number, a --root directory doesn’t exist, the --apigenie binary doesn’t exist (a bare name is looked up in PATH), or, without --apigenie, no apigenie is next to apigenie-mcp or in PATH, or another usage error. |
See the exit statuses shared by the five binaries; apigenie-mcp
never exits with 1.
Tools
| Tool | Arguments | What it returns |
|---|---|---|
lint |
files, config, (fix) |
The lint report: every problem with its rule, severity, line and column. |
check_breaking_changes |
file, base_file or base_ref, config |
The diff report of the file against an earlier version: another file, or the file at a git revision (main, v1.2.0, HEAD~1). |
changelog |
file, revisions, tag_pattern, from, to, config |
The changelog report of the file through its git history. |
format |
file, config, (check) |
The format report, with the formatted text when the file isn’t formatted. |
bundle |
file, (output) |
The file and the local files it references, as one document. |
describe |
file |
The outline of the API: names, without the schemas themselves (see The outline). |
| Argument | Tools | Value |
|---|---|---|
files |
lint |
Required: the files to lint, at least 1. |
file |
all but lint |
Required: the API description. |
config |
lint, check_breaking_changes, changelog, format |
The configuration file, inside the workspace. By default, the one found from the directory of the file (for lint, of the first file) up to the root of its repository. |
base_file, base_ref |
check_breaking_changes |
Exactly one: the earlier version as another file, or as the file at a git revision (a branch, a tag or a commit). |
revisions |
changelog |
commits (default): every commit that changes the file. tags: every release tag. |
tag_pattern |
changelog |
With revisions: tags: the glob of the release tags, e.g. v* (default *, every tag). |
from, to |
changelog |
The revision the changelog starts after (default: the first version of the file) and the last one (default: HEAD). Only committed versions are compared. |
fix |
lint, with --allow-write |
true applies the fixes in the files (default false). |
check |
format, with --allow-write |
true (default) leaves the file alone; false formats it in place. |
output |
bundle, with --allow-write |
The file to write the bundle to; its extension selects JSON or YAML for an OpenAPI, Swagger or AsyncAPI document. |
The result of lint, check_breaking_changes, changelog and format starts with a sentence
that sums up the report (“1 breaking change, 0 non-breaking and 2 non-functional. The check fails:
clients of the earlier version may break.”). The report follows as structured content and as JSON
text. When the file isn’t formatted and check is true, format adds the formatted text as an
embedded resource; with check: false it rewrites the file and the sentence says so.
bundle returns a sentence and the bundled document as an embedded resource, or only the sentence
when it writes to output. describe returns the outline as structured content and as JSON text,
with no sentence. Findings are ordinary results. A file that can’t be read is a result marked as
an error, with the messages of the command.
The outline
| Family | Members |
|---|---|
| OpenAPI, Swagger 2.0 | specVersion, title, version, servers (URLs; Swagger: host and base path), operations (method, path, operationId, summary, tags, deprecated), schemas (names) |
| AsyncAPI 3.0, 3.1 | specVersion, title, version, servers (name, host, protocol), channels (name, address), operations (name, action, channel, summary), messages (names) |
| Protobuf | syntax, package, services (name, methods: name, input, output, clientStreaming, serverStreaming), messages, enums (full names) |
| GraphQL | operations (type: query, mutation or subscription; name: the field), types (name, kind) |
Each outline also has file, family (openapi, swagger, asyncapi, protobuf or graphql)
and issues (severity, message, line). An AsyncAPI 2.x document has no outline: describe
returns a result marked as an error. tags, deprecated, clientStreaming and serverStreaming
are left out when empty or false; the issues of an OpenAPI or Swagger outline are always empty.
Writing files
Without --allow-write no tool writes into the workspace: format and bundle return the
document instead, and the arguments in parentheses above don’t exist. With it, lint takes fix,
format takes check: false to format the file in place, and bundle takes an output file.
Where files may be
The workspace is the roots the client gives, else the --root directories, else the directory the
server runs in. A relative path is resolved against the first directory of the workspace, and an
absolute path must be inside one of them. A path outside them is refused before anything runs. A
client of MCP revision 2025-11-25 or later gets a result marked as an error; an older one gets a
JSON-RPC “invalid params” error (-32602). Arguments the input schema rules out get the same
answers.
Everything the commands read stays inside the workspace too. A file that an OpenAPI, Swagger or
AsyncAPI description references with $ref can’t be read outside it, nor can a Protobuf import or
a configured dictionary or import directory. The command fails on it.
Two exceptions keep a workspace that is a directory of a larger repository working:
- The configuration file above the workspace. The tools look for the configuration file as the
commands do: from the directory of the file up to the root of its git repository, or of the file
system outside a repository. The tools use the file they find even when it is above the
workspace, such as the
apigenie.yamlthatapigenie initwrites at the root of a repository. Only that file: a ruleset or a dictionary it names must be inside the workspace. - The git repository the workspace is in.
check_breaking_changeswithbase_refandchangelogread the history of the repository, wherever it keeps it. A.gitthat leads out of the workspace is read only when it is the.gitfile of a worktree (git worktree add) or a submodule. A.gitthat leads to another repository is refused with a result marked as an error, and so are acommondirorobjects/info/alternatesthat lead out. A partial clone (git clone --filter=...) whose.gitis in the workspace is refused the same way, as it fetches missing objects by running what its configuration names.
Configuration
apigenie-mcp has no settings in apigenie.yaml; the tools read the file as the commands do (see
Where files may be).
See also
- Work with AI agents: the instructions and the loop of an agent that edits API descriptions.
apigenie init:apigenie.yamland the section ofAGENTS.md.- JSON output: the reports the tools return.