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 --help says 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.yaml that apigenie init writes 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_changes with base_ref and changelog read the history of the repository, wherever it keeps it. A .git that leads out of the workspace is read only when it is the .git file of a worktree (git worktree add) or a submodule. A .git that leads to another repository is refused with a result marked as an error, and so are a commondir or objects/info/alternates that lead out. A partial clone (git clone --filter=...) whose .git is 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

Was this helpful?