Large APIs

Large specs can produce hundreds of tools. Most MCP clients show every tool to the model, so a smaller, focused set is usually easier for the model to choose from. The generator gives you four ways to choose.

1. Mark operations with x-mcp#

The x-mcp vendor extension is supported at the root, path and operation levels.

• Values: true or false (booleans, or the strings "true"/"false", case-insensitive). Other values are ignored.
• Precedence: operation, then path, then root. The first defined value wins.
• Default: included, unless you pass --default-include false.

# Optional root-level default
x-mcp: true

paths:
  /pets:
    x-mcp: false        # exclude every operation under /pets
    get:
      x-mcp: true       # but include this one

  /users/{id}:
    get:
      # no x-mcp: included by default

2. Opt in instead of out#

For big APIs it is often simpler to exclude everything by default and mark only the operations you want:

openapi-mcp-generator -i ./openapi.json -o ./my-mcp --default-include false

Then add x-mcp: true to the chosen operations.

3. Filter from the command line#

Curate tools without editing the spec:

openapi-mcp-generator -i ./openapi.json -o ./my-mcp \
  --include-tags pets,store --exclude-operations deletePet

• --include-tags / --exclude-tags match operation tags case-insensitively.
• --include-operations / --exclude-operations match the operationId or the generated tool name.
• Filters apply after x-mcp and --default-include, so they never bring back an excluded operation. Include lists combine (an operation is kept if it matches any), and exclusions always win.

4. Filter in code#

With the Programmatic API you can use the same tag and operation filters, or filter by method, path, annotations or security:

const tools = await getToolsFromOpenApi('./openapi.json', {
  excludeOperations: ['deleteUser'],
  filterFn: (tool) => tool.method.toLowerCase() === 'get' && tool.pathTemplate.startsWith('/users'),
});

Tool names and the 64-character limit#

Some clients cap tool names at 64 characters (Claude Desktop does). --max-tool-name-length defaults to 64:

1. Names that fit are left unchanged.
2. Longer names are word-abbreviated: the leading word is kept, short words are kept and longer words are shortened to their first four characters. For example FDA_get_info_on_conditions_for_doctor_consultation_by_drug_name becomes FDA_get_info_on_cond_for_doct_cons_by_drug_name.
3. If that still overflows, the name falls back to a deterministic hash truncation.
4. Collisions are resolved with a content hash of the operationId, so names stay stable when the spec is reordered.

openapi-mcp-generator -i ./openapi.json -o ./my-mcp --max-tool-name-length 48

Clear operationIds in your spec give the best tool names.

Tips#

• Start with read-only (GET) tools, and add write operations deliberately. Tools carry read-only and destructive hints so clients can ask before running writes; adjust them with x-mcp-annotations.
• Give tools friendly names with x-mcp-title; otherwise the operation summary is used.
• Remove deprecated operations. They are marked [DEPRECATED] in tool descriptions.
• Write good summary and description fields. They become the tool descriptions the model reads.