# apigenie-generator server mcp

Source: https://apigenie.pl/docs/reference/generator/server-mcp
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 2, experimental](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · 1 feature of the fixture not supported yet · [Verification](#verification)

Generate a [Model Context Protocol](https://modelcontextprotocol.io) server in TypeScript from an
OpenAPI document, so that AI agents call the API through typed tools.

> **(experimental, outside the 1.0 compatibility promise)** MCP and its SDK are still moving, and
> tool names and result shapes can change with them. `server mcp` says so in its `--help` and on
> the first line it prints, on the standard error. See the
> [experimental commands](/docs/reference/cli#experimental-commands).

## Usage

```sh
apigenie-generator server mcp [...OPTIONS] INPUT_FILE
```

## Description

The input must be an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see
[Swagger 2.0 input](/docs/reference/generator#swagger-20-input)); bundle documents referencing other
files with [`apigenie bundle`](/docs/reference/cli/bundle).

The generated npm package is a server on the official MCP SDK
([`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server) 2),
which MCP clients (Claude Code, Claude Desktop, IDEs) start and talk to over stdio:

| File             | Content                                                                         |
| ---------------- | ------------------------------------------------------------------------------- |
| `src/client/`    | a [fetch client](/docs/reference/generator/client-fetch) of the API, which the tools call |
| `src/schemas.ts` | [Zod](https://zod.dev) (v4) schemas of the components, and of the arguments and results of the tools |
| `src/tools.ts`   | `registerTools(server)`, registering a tool per operation                         |
| `src/config.ts`  | the base URL, whether operations go to their own servers, the credentials and the client certificate, read from environment variables |
| `src/runtime.ts` | the call of an operation and its result as a tool result                         |
| `src/server.ts`  | `createServer()`, an `McpServer` with the tools                                  |
| `src/index.ts`   | the entry point (the package's `bin`): the server on stdio                      |
| `README.md`      | the environment variables, the tools, and how to add the server to a client     |

```sh
apigenie-generator server mcp openapi.yaml -o petstore-mcp
cd petstore-mcp && npm install && npm run build
claude mcp add petstore --env PET_STORE_BASE_URL=https://petstore.example.com/v1 -- node "$PWD/dist/index.js"
```

### Tools

Every operation becomes a tool:

- its name is the `operationId`, with other characters than letters, digits, `_` and `-` replaced
  by `_` (at most 64 characters), or the name of the client's function for operations without one;
- its title is the summary, and its description the summary and the description (or the method and
  path), starting with "Deprecated." for deprecated operations;
- its arguments are the parameters, by name, and the request body as `body` (`requestBody` when a
  parameter is named `body`), validated by their schemas before the API is called. Binary bodies,
  and the files of `multipart/form-data` bodies, are base64-encoded strings. Since 0.12.0, a body
  that the operation accepts in several media types of one kind (two JSON patch formats, for
  example) takes any of their schemas. The `contentType` argument (`bodyContentType` when a
  parameter has that name) names the one sent, the first of them in the document by default, and
  the body has to match its schema (a media type without a schema takes any body);
- since 0.12.0, a oneOf with a discriminator and a `defaultMapping` (`x-defaultMapping` in 3.0
  and 3.1 documents) validates a value (an argument or a result) against the option its property
  selects, or against the default one when the property is missing or its value isn't mapped. The
  members of the oneOf have to be local references; a `defaultMapping` naming none of them is
  reported as a warning and ignored;
- GET, HEAD and QUERY operations are marked read-only, DELETE operations destructive, and PUT and
  DELETE operations idempotent.

A tool returns the status and the body of the response, as structured content
(`{ "status": 200, "body": ... }`) described by the tool's output schema, and as JSON text. Binary
bodies are returned as an embedded resource, with `{ status, contentType, size }`. A failed request
is an error result with the status and the body of the response, and so is a response the API
document doesn't describe, which lists what doesn't match.

Operations with `x-mcp: false`, on the operation or its path item, don't become tools, nor do
operations marked `x-internal: true` (unless `internal_operations` is set) or disabled with
`x-apigenie`.

```yaml
paths:
  /admin/reset:
    post:
      x-mcp: false
```

### Environment variables

The server reads its settings from environment variables, prefixed by the API title in upper
snake case (`PET_STORE` for "Pet Store", see `env_prefix`). They hold the base URL of the API,
whether operations with servers of their own are sent there, and the credentials and TLS files of
its security schemes:

| Variable                                         | Value                                                 |
| ------------------------------------------------ | ----------------------------------------------------- |
| `<PREFIX>_BASE_URL`                              | base URL of the API; the first server of the document by default |
| `<PREFIX>_OPERATION_SERVERS`                     | since 0.12.0, `true` sends an operation with servers of its own to the first of them, `false` to the base URL; by default `true` while `<PREFIX>_BASE_URL` isn't set (`false` with `--mock`); case is ignored, and any other value makes the server exit with status 1 at start |
| `<PREFIX>_<SCHEME>`                              | API key of an `apiKey` scheme                          |
| `<PREFIX>_<SCHEME>_TOKEN`                        | token of an HTTP `bearer` scheme                       |
| `<PREFIX>_<SCHEME>_USERNAME`, `..._PASSWORD`     | user name and password of an HTTP `basic` scheme      |
| `<PREFIX>_<SCHEME>_ACCESS_TOKEN`                 | access token of an `oauth2` or `openIdConnect` scheme |
| `<PREFIX>_<SCHEME>_CERT`, `..._KEY`              | since 0.12.0, paths of the PEM files of the client certificate and its key, of a `mutualTLS` scheme; set both or neither. Only one of them set, or a file that can't be read, makes the server exit with status 1 at start |
| `<PREFIX>_<SCHEME>_CA`                           | since 0.12.0, path of the PEM file of the CA bundle the API's certificate is checked against, in place of the default CAs, of a `mutualTLS` scheme; optional. A file that can't be read makes the server exit with status 1 at start |

`<SCHEME>` is the name of the scheme in upper snake case (`apiKey` gives `API_KEY`). The generated
`README.md` lists the variables of the API. Since 0.12.0, when `<PREFIX>_<SCHEME>_CERT` and
`<PREFIX>_<SCHEME>_KEY` are set, the server presents that client certificate on every
connection, to every server of the API, through an [undici](https://undici.nodejs.org) `Agent`.
`<PREFIX>_<SCHEME>_CA` alone makes the server check the API's certificate against that bundle
instead of the default CAs, without presenting a client certificate.
Only the first `mutualTLS` scheme of the document (OpenAPI 3.1 and 3.2) has these variables; the
generator warns about the others. A package generated from such a document depends on `undici` 7.

### Mock server

With `--mock`, the package also contains the document (`openapi.json`) and an `npm run mock`
script serving it with [`apigenie-server`](/docs/reference/server), and the tools call
`http://127.0.0.1:4010` when no base URL is set, with the placeholder `mock` for the credentials
that aren't set (the mock server only checks that they are present): a demo of the tools needs no
running API and no credentials.

```sh
apigenie-generator server mcp openapi.yaml -o petstore-mcp --mock
cd petstore-mcp && npm install && npm run build
npm run mock    # in another terminal
```

## Extensions

| Extension | Effect |
| --------- | ------ |
| `x-mcp` | `false` on an operation or its path item: the operation isn't a tool |
| `x-internal` | `true` on an operation or its path item leaves it out, unless `internal_operations` is set |
| `x-apigenie.codegen.disabled` | `true` on an operation or its path item leaves it out |

The extensions can live in an overlay for this target instead of in the document, e.g.
`mcp.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: MCP tools
  version: 1.0.0
actions:
  - target: $.paths['/admin/reset'].post
    update:
      x-mcp: false
```

```sh
apigenie-generator server mcp openapi.yaml --overlay mcp.overlay.yaml -o out
```

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.server_mcp.overlay` in the configuration file (with paths relative
to it). Warnings and errors about a value an overlay set point to the overlay.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Directory where the package is generated.

### --package-name

Name of the package and of the MCP server, `<title>-mcp` by default.

### --package-version

Version of the package and of the MCP server, the version of the API by default.

### --mock

Make the tools call `apigenie-server` mocking the API when no base URL is set, as described
above. Same as `mock: true`.

## Configuration

```yaml
version: '1.0'
commands:
  generate:
    server_mcp:
      include_tags: [pets, store]
      env_prefix: PETSTORE
```

| Option                | Description                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `include_tags`        | only the operations with one of these tags become tools (a list or a comma-separated string); all by default |
| `exclude_tags`        | the operations with one of these tags don't become tools                                                     |
| `internal_operations` | `true` also makes tools of the operations marked `x-internal: true` (default: `false`)                       |
| `env_prefix`          | prefix of the environment variables, e.g. `PETSTORE`; the API title in upper snake case by default           |
| `output_schema`       | `false` leaves out the output schemas of the tools (default: `true`)                                        |
| `mock`                | `true` points the tools at `apigenie-server` by default, as `--mock` does (default: `false`)                 |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#openapi).

This target's support tier is [Tier 2, experimental](/docs/reference/generator/conformance#tiers). It goes through all three levels like Tier 2, but follows a specification and SDK that are still changing. It is outside the [1.0 compatibility promise](/docs/reference/cli/compatibility): its options and the shape of its output can change, or it can go away, in a minor release.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 34 supported, 1 not yet, 2 not checked | ✓ pass (Version 6.0.3, ESLint 10 + typescript-eslint 8, @modelcontextprotocol/server 2) | ✓ 38 of 39 operations pass, 1 known failure (node) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 34 supported, 1 not yet, 2 not checked | runs before a release | runs before a release, 1 known failure |

Not supported yet, as the target's manifest says:

- `schemas.read-write-only`: readOnly and writeOnly are ignored; one schema serves arguments and results, so createWebhookSubscription's result declares the writeOnly `secret`.
