apigenie-generator server mcp
Tier 2, experimental · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · 1 feature of the fixture not supported yet · Verification
Generate a Model Context Protocol 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 mcpsays so in its--helpand on the first line it prints, on the standard error. See the experimental commands.
Usage
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); bundle documents referencing other
files with apigenie bundle.
The generated npm package is a server on the official MCP SDK
(@modelcontextprotocol/server 2),
which MCP clients (Claude Code, Claude Desktop, IDEs) start and talk to over stdio:
| File | Content |
|---|---|
src/client/ |
a fetch client of the API, which the tools call |
src/schemas.ts |
Zod (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 |
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(requestBodywhen a parameter is namedbody), validated by their schemas before the API is called. Binary bodies, and the files ofmultipart/form-databodies, 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. ThecontentTypeargument (bodyContentTypewhen 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-defaultMappingin 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; adefaultMappingnaming 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.
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 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, 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.
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:
overlay: 1.0.0
info:
title: MCP tools
version: 1.0.0
actions:
- target: $.paths['/admin/reset'].post
update:
x-mcp: false
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.
-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
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 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.
This target's support tier is Tier 2, experimental. 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: 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 writeOnlysecret.