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 mcp says so in its --help and 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 (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.

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.

ResultsLevel 1Level 2Level 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 checkedruns before a releaseruns 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.
Was this helpful?