# apigenie-mcp

Source: https://apigenie.pl/docs/reference/cli/mcp
See also: [Configuration](https://apigenie.pl/docs/reference/cli/configuration.md), [Formats](https://apigenie.pl/docs/reference/cli/formats.md), [Specification extensions](https://apigenie.pl/docs/reference/cli/extensions.md), [faker](https://apigenie.pl/docs/reference/cli/faker.md), [Compatibility](https://apigenie.pl/docs/reference/cli/compatibility.md).

`apigenie-mcp` (since 0.12.0) gives coding agents the checks of the CLI as tools of the
[Model Context Protocol](https://modelcontextprotocol.io): 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

```sh
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:

```json
{
  "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](/docs/reference/cli#exit-status) shared by the five binaries; `apigenie-mcp`
never exits with 1.

## Tools

| Tool | Arguments | What it returns |
| ---- | --------- | --------------- |
| `lint` | `files`, `config`, (`fix`) | The [lint report](https://apigenie.pl/schemas/apigenie-lint-report.json): every problem with its rule, severity, line and column. |
| `check_breaking_changes` | `file`, `base_file` or `base_ref`, `config` | The [diff report](https://apigenie.pl/schemas/apigenie-diff-report.json) 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](https://apigenie.pl/schemas/apigenie-changelog-report.json) of the file through its git history. |
| `format` | `file`, `config`, (`check`) | The [format report](https://apigenie.pl/schemas/apigenie-format-report.json), 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](#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`](/docs/reference/cli/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](#where-files-may-be)).

## See also

- [Work with AI agents](/docs/guides/work-with-ai-agents): the instructions and the loop of an
  agent that edits API descriptions.
- [`apigenie init`](/docs/reference/cli/init): `apigenie.yaml` and the section of `AGENTS.md`.
- [JSON output](/docs/reference/cli#json-output): the reports the tools return.
