The openapi2mcp command converts OpenAPI files to Kong’s decK format with MCP (Model Context Protocol) configuration.
deck file openapi2mcp
Uses:
deck
Related Documentation
MCP tool generation
This command generates a Kong Gateway Service with an MCP route that includes the AI MCP Proxy plugin configured with tools derived from the OpenAPI specification operations.
Each OpenAPI spec component is mapped to an MCP tool definition:
|
Component |
MCP tool mapping |
|---|---|
operationId
|
Tool name (kebab-case normalized) |
| Summary/description | Tool description |
| Parameters | Tool parameters array |
requestBody
|
Tool request_body
|
Security/ACL generation
When an OAuth2 security scheme includes the x-kong-mcp-acl extension, ACL entries
are automatically generated for each tool based on the operation’s security scopes.
The plugin config will include acl_attribute_type, access_token_claim_field, and per-tool acl.allow arrays.
- Use
x-kong-mcp-default-aclat the document level to set a default ACL for the plugin. - Use
--ignore-security-errorsto skip unsupported security configurations instead of failing.
Supported extensions
Supported x-kong extensions:
|
Annotation |
Description |
|---|---|
x-kong-name
|
Custom entity naming. |
x-kong-tags
|
Tags for all entities. |
x-kong-service-defaults
|
Service entity defaults. |
x-kong-route-defaults
|
Route entity defaults. |
x-kong-upstream-defaults
|
Upstream entity defaults. |
x-kong-plugin-*
|
Additional plugins. |
Supported MCP-specific extensions:
|
Annotation |
Description |
|---|---|
x-kong-mcp-tool-name
|
Override generated tool name. |
x-kong-mcp-tool-description
|
Override tool description. |
x-kong-mcp-exclude
|
Exclude operation from tool generation (boolean). |
x-kong-mcp-proxy
|
Override AI MCP Proxy plugin config at document level. |
Supported security extensions:
|
Annotation |
Description |
|---|---|
x-kong-mcp-acl
|
ACL config on OAuth2 security scheme (acl_attribute_type, access_token_claim_field).
|
x-kong-mcp-default-acl
|
Default ACL array at document level (scope, allow).
|
Convert an OpenAPI file to a Kong state file with MCP config
Converting an OpenAPI file to a Kong declarative configuration with MCP configuration can be done in a single command:
deck file openapi2mcp --spec oas.yaml --output-file kongmcp.yaml
Copied!
Command usage
Usage:
deck file openapi2mcp [flags]
Flags:
--format string output format: yaml or json (default "yaml")
-h, --help help for openapi2mcp
--ignore-security-errors Ignore errors for unsupported security schemes or missing x-kong-mcp-acl extensions.
--include-direct-route Also generate non-MCP routes for direct API access.
-m, --mode string ai-mcp-proxy mode: 'conversion' (client mode) or 'conversion-listener' (server mode). (default "conversion-listener")
--no-id Do not generate UUIDs for entities.
-o, --output-file string Output file to write. Use - to write to stdout. (default "-")
-p, --path-prefix string Custom path prefix for the MCP route (default: /{service-name}-mcp).
--select-tag strings Select tags to apply to all entities. If omitted, uses the "x-kong-tags"
directive from the file.
-s, --spec string OpenAPI spec file to process. Use - to read from stdin. (default "-")
--uuid-base string The unique base-string for uuid-v5 generation of entity IDs. If omitted,
uses the root-level "x-kong-name" directive, or falls back to 'info.title'.
Copied!