AI MCP Proxy

The AI MCP Proxy plugin lets you connect any Kong-managed Service to the Model Context Protocol (MCP). It acts as a protocol bridge, translating between MCP and HTTP so that MCP-compatible clients can either call existing APIs or interact with upstream MCP servers through Kong.

The plugin’s mode parameter controls whether it proxies MCP requests, converts RESTful APIs into MCP tools, or exposes grouped tools as an MCP server. This flexibility allows you to integrate existing HTTP APIs into MCP workflows, front third-party MCP servers with Kong’s policies, or expose multiple tool sets as a managed MCP server.

Because the plugin runs directly on Kong AI Gateway, MCP endpoints are provisioned dynamically on demand. You don’t need to host or scale them separately, and the Kong AI Gateway applies its authentication, traffic control, and observability features to MCP traffic at the same scale it delivers for traditional APIs.

Note: Unlike other available AI plugins, the AI MCP Proxy plugin is not invoked as part of an LLM request flow. Instead, it’s part of an MCP request flow. It’s registered and executed as a regular plugin, between the MCP client and the MCP server, allowing it to capture MCP traffic independently of LLM request flow.

Do not configure the AI MCP Proxy plugin together with other AI plugins on the same Service or Route.

The AI MCP Proxy bridges the Kong plugin ecosystem with the MCP world, enabling you to bring all of Kong’s traffic management, security, and observability capabilities to MCP endpoints:

The AI MCP Proxy plugin handles MCP requests by converting them into standard HTTP calls and returning the responses in MCP format. The flow works as follows:

1. Accepts MCP protocol requests from a client.
2. Parses the MCP tool call and matches it to an OpenAPI operation.
3. Converts the operation into a standard HTTP request.
4. Sends the request to the upstream Service.
5. Wraps the HTTP response in MCP-compatible format and returns it.

 
sequenceDiagram
    participant C as MCP Client
    participant K as Kong (AI MCP Proxy plugin)
    participant U as Upstream Service

    C->>K: MCP request (tool invocation)
    activate K
    K->>K: Parse MCP payload
    K->>K: Map to HTTP endpoint (OpenAPI schema)
    K->>U: HTTP request
    deactivate K
    activate U
    U-->>K: HTTP response
    deactivate U
    activate K
    K->>K: Convert to MCP format
    K-->>C: MCP response
    deactivate K
  

Pings from your MCP client are included in the total request count for your Kong AI Gateway instance, in addition to the requests made to the MCP server.

Before using the AI MCP Proxy plugin, ensure your setup meets these requirements:

• The upstream Service exposes a valid OpenAPI schema.
• That Service is configured and accessible in Kong.
• An MCP-compatible client (such as Insomnia, Claude, Cursor, or LMstudio) is available to connect to Kong.
• The Kong AI Gateway instance supports the AI MCP Proxy plugin (is 3.12 or higher).

The AI MCP Proxy plugin operates in four modes, controlled by the config.mode parameter. Each mode determines how Kong handles MCP requests and whether it converts RESTful APIs into MCP tools.

When exposing MCP servers through Kong Gateway, you may need granular control over which authenticated API consumers can discover and invoke specific tools. The AI MCP Proxy plugin’s ACL feature lets you define access rules at both the default level (applying to all tools) and per-tool level (for fine-grained exceptions)

This way, consumers only interact with tools appropriate to their role, while maintaining a complete audit trail of all access attempts. Authentication is handled by standard Kong AuthN plugins (for example, Key Auth or OIDC flows), and the resulting Consumer identity is used for ACL checks.

ACL in listener Mode

Listener mode does not support direct ACL configuration. Instead, it inherits ACL rules from tagged conversion-listener or conversion-only plugins.

To use ACLs with listener mode:

1. Configure conversion-listener or conversion-only plugins with ACL rules and tags
2. Configure listener mode to aggregate tools by matching tags
3. Listener mode enforces ACL rules from the conversion plugins.

Supported identifier types

ACL rules can reference Consumers and Consumer Groups using these identifier types in allow and deny lists:

• username: Consumer username
• id: Consumer UUID
• custom_id: Custom Consumer identifier
• consumer_groups.name: Consumer Group name

The authenticated Consumer identity is matched against these identifiers. If the Consumer or any of their Consumer Groups match an ACL entry, the rule applies.

How default and per-tool ACLs work

The plugin evaluates access using a two-tier system:

If a tool defines its own ACL, the plugin ignores default_acl for that tool:

• Tools with no ACL configuration inherit the default rules (both allow and deny lists)
• Tools with an ACL must explicitly list all allowed subjects (even if they were already in default_acl)

ACL evaluation logic

Both default and per-tool ACLs use allow and deny lists. Evaluation follows this order:

1. Deny list configuration: If a deny list exists and the subject matches any deny entry, the request is rejected (INVALID_PARAMS -32602).
2. Allow list configuration: If an allow list exists, the subject must match at least one entry; otherwise, the request is denied (INVALID_PARAMS -32602).
3. No allow list configuration: If no allow list exists and the subject is not in deny, the request is allowed.
4. No ACL configuration: If neither list exists, the request is allowed.

All access attempts (allowed or denied) are written to the plugin’s audit log.

The table below summarizes the possible ACL configurations and their outcomes.

ACL tool control request flow

The AI MCP Proxy plugin evaluates ACLs for both tool discovery and tool invocation. These are two distinct operations with different behaviors:

Tool Discovery (List tools):

1. MCP client requests the list of available tools
2. Kong AuthN plugin validates the request and identifies the Consumer
3. AI MCP Proxy loads the Consumer’s group memberships
4. Plugin evaluates each tool against the default_acl
5. Plugin returns an HTTP 200 response with only the tools the Consumer is allowed to access
6. Plugin logs the discovery attempt

Tool invocation:

1. MCP client invokes a specific tool
2. Kong AuthN plugin validates the request and identifies the Consumer
3. AI MCP Proxy loads the Consumer’s group memberships
4. Plugin evaluates the tool-specific ACL if it exists, or the default ACL otherwise
5. Plugin logs the access attempt (allowed or denied)
6. Plugin returns INVALID_PARAMS -32602 if denied, or forwards the request to the upstream MCP server if allowed

 
sequenceDiagram
  participant Client as MCP Client
  participant Kong as Kong Gateway
  participant Auth as AuthN Plugin
  participant ACL as ai-mcp-proxy (ACL/Audit)
  participant Up as Upstream MCP Server
  participant Log as Audit Sink

  %% ----- List Tools -----
  rect
    note over Client,Kong: List Tools (Default ACL Scope)
    Client->>Kong: GET /tools
    Kong->>Auth: Authenticate
    Auth-->>Kong: Consumer identity
    Kong->>ACL: Evaluate scoped default ACL
    ACL-->>Log: Audit entry
    alt Allowed
      Kong-->>Client: Filtered tool list
    else Denied
      Kong-->>Client: INVALID_PARAMS -32602
    end
  end

  %% ----- Tool Invocation -----
  rect
    note over Client,Up: Tool Invocation (Per-tool ACL)
    Client->>Kong: POST /tools/{tool}
    Kong->>Auth: Authenticate
    Auth-->>Kong: Consumer identity
    Kong->>ACL: Evaluate per-tool ACL
    ACL-->>Log: Audit entry
    alt Allowed
      Kong->>Up: Forward request
      Up-->>Kong: Response
      Kong-->>Client: Response
    else Denied
      Kong-->>Client: INVALID_PARAMS -32602
    end
  end
  

For users already using the AI MCP Proxy plugin without ACL configuration, follow these steps to add ACL tool control:

1. Add an AuthN plugin: Enable an authentication plugin such as Key Auth to work with Consumers and Consumer Groups.
2. Add ACL fields to the plugin configuration: Update the AI MCP Proxy plugin schema to include default_acl and per-tool acl fields.
3. Configure ACL rules: Add allow and deny lists to control access at the default and per-tool levels.
4. Enable audit logging: Set logging.log_audits: true to monitor access attempts and verify ACL enforcement.

The AI MCP Proxy plugin provides support for MCP operations and upstream interactions, while certain advanced features and non-HTTP protocols are not currently supported. The table below summarizes what is supported and what is outside the current scope.