AI MCP Servers

Create an AI MCP Server to connect AI applications such as Claude, Cursor, or Insomnia to your APIs and tools through the standardized Model Context Protocol. An AI MCP Server acts as a bridge between MCP-compatible clients and your backend systems, allowing you to expose existing APIs as discoverable tools without building custom integrations for each AI client.

Because MCP endpoints run directly on AI Gateway, you don’t need to host and scale MCP infrastructure separately. The same authentication, rate limiting, and observability policies you apply to traditional API traffic automatically cover MCP traffic, giving you consistent governance across both HTTP and MCP clients.

Note: MCP traffic is API-level traffic, not LLM request/response flows. Authenticate MCP traffic through an AI Auth Strategy referenced in access.auth_strategies, the same as AI Models and AI Agents. Standard API-level policies (rate limiting, logging) still apply to MCP traffic through the policies field. AI Policies that operate on LLM prompt/response flows (such as prompt guards or model routing) won’t apply here.

AI MCP Servers can be created and managed through the:

• Konnect UI
• AI Gateway API: /v1/ai-gateways/{aiGatewayId}/mcp-servers
• kongctl

For configuration examples and step-by-step setup instructions, see Set up an AI MCP Server.

Attach AI Policies to AI MCP Servers to enforce rate limits, request/response transformation, logging, and OAuth-based ACL gating. Add them to the policies field by name or ID. AI Policies run on all MCP traffic through the server, before tool invocation and after ACL checks. Multiple AI Policies can attach to one AI MCP Server, and each runs independently in the request lifecycle. Authenticating AI Consumers isn’t handled through the policies field; reference an AI Auth Strategy in access.auth_strategies instead. See Access control.

You can also attach AI Policies at the AI Consumer level for per-client enforcement.

Attach AI Policies to your AI MCP Server for common governance scenarios:

AI Gateway supports five server modes for different integration patterns: exposing REST APIs as discoverable MCP tools, proxying requests to existing MCP servers with added authentication and observability, or aggregating tools from multiple sources into a single endpoint. Select the mode that fits your use case using the type field. Regardless of mode, AI Gateway generates MCP observability metrics for all traffic through the server.

For conversion-listener, conversion-only, and listener modes, the runtime converts MCP requests into HTTP calls and wraps the responses back in MCP format:

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

For passthrough-listener mode, the runtime proxies MCP traffic directly to the upstream MCP server without conversion.

 
sequenceDiagram
    participant Client as MCP Client
    participant Gateway as AI Gateway
(MCP Server)
    participant Upstream as Upstream Service

    Client->>Gateway: MCP request (tool invocation)
    activate Gateway
    Gateway->>Gateway: Parse MCP payload
    Gateway->>Gateway: Map to HTTP endpoint
    Gateway->>Upstream: HTTP request
    deactivate Gateway
    activate Upstream
    Upstream-->>Gateway: HTTP response
    deactivate Upstream
    activate Gateway
    Gateway->>Gateway: Convert to MCP format
    Gateway-->>Client: MCP response
    deactivate Gateway
  

Pings from MCP clients are included in the total request count for an AI Gateway instance, in addition to requests made to the MCP server itself.

Forward proxy support

Set config.proxy on this entity to route its outbound requests through an HTTP forward proxy. Use this in network-isolated deployments where AI Gateway cannot open direct connections to LLM providers or auxiliary services.

The proxy record is identical for AI Model, AI MCP Server, and supported AI Policy entities. Existing capabilities such as load balancing, health checking, streaming, WebSocket, and HTTP/2 continue to work when the proxy is active.

For the full field reference, traffic flow, and limitations, see Forward proxy support.

You can use a listener AI MCP Server to pull tools from multiple upstream-server AI MCP Servers and expose them through a single endpoint. The listener discovers and aggregates tools based on entries in its sources field, so clients see one unified tool catalog while your services remain independent.

How aggregation works

1. Sources connect upstreams to listeners: Set the listener’s top-level sources field to the immutable name of each upstream-server (or conversion-only) AI MCP Server whose tools it should expose (for example, sources: [weather-service, catalog-service]). Every AI MCP Server named in sources gets pulled into the aggregation.

2. Tool discovery: When an MCP client calls tools/list, the listener fetches tool lists from every matching upstream. If an upstream requires authentication, configure config.server.tools_list_auth with OAuth2 credentials so the listener can fetch its tools.

3. Tool caching: Each upstream-server caches its tool list for the duration specified by config.tools_cache_ttl_seconds. Set to 0 to fetch fresh on every client request.

4. Tool name disambiguation: If two upstreams expose tools with the same name, the listener prepends the service name to avoid collisions (e.g., weather-service/get-forecast). Disable this with config.server.preserve_upstream_tool_names: true if you’re sure names won’t collide.

5. Tool invocation: When a client calls a tool, the listener routes the request to whichever upstream registered it. From the client’s perspective, it’s one call to one URL.

 
sequenceDiagram
    participant Agent as AI Agent
    participant Kong as AI Gateway
    participant Listener as AI MCP Server
    participant Upstreams as Upstreams
(sources: weather-service, catalog-service)

    note over Agent,Upstreams: Phase 1: Token Validation
    Agent->>Kong: Bearer token
    Kong->>Kong: Validate & exchange token
    Kong->>Listener: Pass request

    note over Agent,Upstreams: Phase 2: Tools List Aggregation
    Agent->>Kong: tools/list
    Kong->>Listener: tools/list
    Listener->>Upstreams: Query all matching upstreams
    Upstreams-->>Listener: Tool lists
    Listener-->>Kong: Merged list
    Kong-->>Agent: Aggregated tools

    note over Agent,Upstreams: Phase 3: Tool Call Routing
    Agent->>Kong: tools/call (tool name)
    Kong->>Listener: Route to upstream
    Listener->>Upstreams: Forward call
    Upstreams-->>Listener: Result
    Listener-->>Kong: Result
    Kong-->>Agent: Tool response
  

Figure 1: This diagram shows how AI Gateway handles requests from an AI agent. It validates the agent’s credentials, collects tool definitions from multiple services, and forwards tool calls to the correct upstream.

Tool-list authentication

By default, the AI MCP Server in listener mode connects to upstreams without credentials. If an upstream MCP server requires authentication, configure config.server.tools_list_auth on the upstream-server. The credential is used only when fetching the upstream’s tool list, not for agent requests. Different upstreams can use different credentials, managed centrally by AI Gateway.

This is distinct from config.upstream.auth, which authenticates the actual tool-call requests forwarded to the upstream service.

Header forwarding

When your upstream services need to enforce their own access controls or apply client-specific logic based on identity, enable config.server.forward_client_headers on the listener or upstream-server. This setting passes the original client’s headers (authentication tokens, context) so upstreams see the actual client, not just the listener.

A tool maps an MCP tool name to an upstream HTTP endpoint. Each tool needs at minimum a description and an HTTP method. The runtime extracts the host, path, headers, and query from the route configuration, so most tool entries don’t need to specify them. Override these on the tool entry only when the route doesn’t match the upstream endpoint exactly.

For richer mapping, supply request_body, responses, and parameters specifications in OpenAPI JSON format. The runtime uses them to validate calls and shape upstream HTTP requests.

Tools can also carry MCP-spec annotations that hint at tool behavior to clients (for example, whether a tool is read-only, idempotent, or destructive). Annotations don’t change runtime behavior; they help clients decide whether to surface a tool, confirm before invocation, or treat it as safe to retry.

Per-tool ACLs override the MCP Server’s default tool ACLs. For more information, see ACL tool control.

Some MCP clients need to maintain state across multiple tool calls such as authentication tokens, conversation context, or request IDs. AI Gateway can manage session state for you in listener and conversion-listener modes, storing it either encrypted on the client or in Redis. Configure session storage through config.server.session. The passthrough-listener mode doesn’t manage sessions because state lives entirely on the upstream MCP server.

There are two session strategies:

1. Client. Session state is encrypted into the MCP session ID assigned to the client. Requires secrets which are encryption keys; the first entry is used for encryption, all entries are used for decryption to support key rotation.
2. Redis. Session state is stored in Redis. Configure connection details and authentication in config.server.session.redis.

If your AI Policy uses a Redis datastore, you can authenticate to it with a cloud Redis provider. This allows you to rotate credentials without relying on static passwords.

The following providers are supported:

• AWS ElastiCache
• Azure Managed Redis
• Google Cloud Memorystore (with or without Valkey)

Each provider also supports an instance and cluster configuration.

Configure how long sessions persist using session_ttl (default 24 hours) to match your application’s needs. If your upstream server already manages state internally, disable AI Gateway’s session management by setting managed: false.

Secrets used in session encryption can be referenced from an AI Vault.

An MCP client such as Claude Desktop, Cursor, or ChatWise handles the following details automatically. They matter when testing an AI MCP Server directly, for example with curl, or when building a custom MCP client.

Streamable HTTP handshake. AI Gateway implements the MCP Streamable HTTP transport. A spec-compliant client performs this sequence before calling tools:

1. Send an initialize request to the route configured on config.route.paths. The response includes an Mcp-Session-Id header.
2. Send a notifications/initialized notification to the same route.
3. Carry the Mcp-Session-Id header on subsequent tools/list and tools/call requests.

Tool argument naming.

Tools generated from parameters (conversion-listener, conversion-only) rename query, path, header, and cookie args to {in}_{name}: query: q becomes query_q. Bodies collapse into a single body property. Check tools/list before calling tools/call.

Once you expose tools through an AI MCP Server, anyone who can reach the endpoint can attempt to call them unless you gate access to known AI Consumers. To authenticate AI Consumers calling a conversion-listener, listener, or passthrough-listener AI MCP Server, reference an AI Auth Strategy by name or ID in the access.auth_strategies array. This is the same mechanism used by AI Models and AI Agents. An AI MCP Server currently accepts up to one AI Auth Strategy reference. The AI MCP Server has its own top-level authentication mechanism, so attaching an authentication AI Policy directly to its policies field isn’t supported; authentication is configured exclusively through AI Auth Strategies. See AI Policy scopes for details.

upstream-server AI MCP Servers don’t accept an access.auth_strategies reference. Configure config.server.tools_list_auth instead to authenticate to the upstream when fetching its tool list; see Tool-list authentication. conversion-only AI MCP Servers have no access field at all, since they never accept incoming MCP traffic directly.

ACLs are evaluated only after the AI Consumer’s identity is resolved through this authentication step. For ACL configuration, see ACL tool control.

Protected resource metadata

If your MCP clients follow the MCP authorization specification’s discovery flow, they need to know which authorization server protects your AI MCP Server before they can request a token, or they fail outright instead of prompting the user through an OAuth flow. To support these clients, advertise OAuth 2.0 Protected Resource Metadata (RFC 9728) through access.metadata on conversion-listener, listener, and passthrough-listener AI MCP Servers.

Configure access.metadata alongside an openid-connect AI Auth Strategy in access.auth_strategies:

Setting access.metadata causes AI Gateway to generate an AI MCP OAuth2 Policy configuration from it and the referenced AI Auth Strategy, and apply it to this AI MCP Server’s route in place of a plain auth-strategy check. You don’t create or attach an AI MCP OAuth2 Policy instance yourself for this. The generated configuration adds OAuth 2.1 resource-server behavior (protected resource metadata serving, token audience validation) that a plain openid-connect check alone doesn’t provide.

Generating an AI MCP OAuth2 Policy configuration is the current mechanism for this OAuth 2.1 resource-server behavior. This is also why access.metadata requires an openid-connect AI Auth Strategy: a future release moves this behavior to native OIDC resource-server support without changing how you configure access.auth_strategies.

Two AI Auth Strategy settings carry forward into the generated configuration: audience_required controls whether the generated configuration enforces the token’s audience against access.metadata.resource, and hide_credentials: false enables credential passthrough on the generated configuration instead of stripping credentials from the request.

access.metadata isn’t supported with a key-auth AI Auth Strategy. key-auth credentials can’t serve OAuth 2.0 Protected Resource Metadata; combining the two is rejected.

If you omit access.metadata, access.auth_strategies still authenticates requests on its own, as a plain key-auth or openid-connect check, without the added OAuth 2.1 resource-server behavior.

Access control and AI Auth Strategies govern who can reach the AI MCP Server. Separately, config.upstream.auth controls how AI Gateway authenticates itself when forwarding tool-call requests to the upstream service. By default, AI Gateway proxies these requests without adding credentials.

This applies to any mode that connects directly to an upstream service: conversion-only, conversion-listener, passthrough-listener, and upstream-server. A listener AI MCP Server has no upstream of its own, since it only aggregates tools from other AI MCP Servers. config.upstream.auth is also distinct from config.server.tools_list_auth, which only authenticates the one-time fetch of an upstream-server’s tool list, not the tool-call requests themselves.

Some upstream services don’t accept bearer tokens or API keys at all, and only accept requests signed with AWS IAM (SigV4), such as a service fronted by an IAM-protected Amazon API Gateway. For these, set config.upstream.auth.type to aws.

AI Gateway signs each proxied request using the credentials you provide:

• Static IAM user credentials, access_key_id and secret_access_key, optionally paired with a session_token for temporary credentials
• Environment auto-detection when you omit access_key_id and secret_access_key, for example, an EC2 instance profile or environment variables
• Role assumption through assume_role_arn and role_session_name, layered on top of either credential source. Recommended for production use and cross-account access.

Set region to override the region. Otherwise, AI Gateway infers from the environment, and sts_endpoint_url to use a custom AWS STS endpoint when assuming a role.

secret_access_key and session_token are write-only and referenceable fields. Store them in a vault instead of in plaintext.

config:
  url: https://tools.execute-api.us-east-1.amazonaws.com/prod
  upstream:
    auth:
      type: aws
      region: us-east-1
      assume_role_arn: arn:aws:iam::123456789012:role/mcp-tool-access
      role_session_name: kong-ai-gateway

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

This way, AI Consumers only interact with tools appropriate to their role, while maintaining a complete audit trail of all access attempts. Authentication is handled by an AI Auth Strategy (key-auth or openid-connect) referenced in the AI MCP Server’s access.auth_strategies array, and the resolved AI Consumer identity is used for ACL checks. See Access control.

ACL in listener mode

listener mode supports direct ACL configuration on the MCP Server itself.

To use ACLs with listener mode:

1. Reference an AI Auth Strategy in access.auth_strategies so requests resolve to an authenticated AI Consumer.
2. Set ACL fields directly on the listener: access.acl_attribute_type, access.access_token_claim_field (when using oauth_access_token), access.acls for server-level fallback rules, access.default_tool_acls for the default tool ACL, and per-tool tools[].access.acls for tool-specific overrides.
3. Configure AI Consumers and AI Consumer Groups to match the allow and deny entries.

ACL behavior:

• access.default_tool_acls applies to all tools by default.
• If access.default_tool_acls isn’t set, the listener falls back to the top-level access.acls.
• A tool’s own acls fully overrides the default ACL for that tool.
• sources is used for tool aggregation, not for inheriting ACLs from other AI MCP Servers.

Attribute types

For modes that support server-level ACL configuration (conversion-listener, listener, passthrough-listener, upstream-server), two attribute types determine what the AI MCP Server evaluates ACL rules against:

1. consumer (default). Evaluates against the resolved AI Consumer identity.
2. oauth_access_token. Evaluates against a claim extracted from the OAuth access token. Set access.access_token_claim_field to a jq filter (for example, .user.email for a nested claim). The token is validated by the openid-connect AI Auth Strategy referenced in access.auth_strategies — on this server if it accepts MCP traffic directly (conversion-listener, listener, passthrough-listener), or on the listener that aggregates it if this is a conversion-only or upstream-server AI MCP Server. If access.metadata is also set, validation happens through the generated AI MCP OAuth2 Policy configuration instead; see Protected resource metadata.

conversion-only AI MCP Servers have no access field of their own, since they never accept incoming MCP traffic directly. They only support per-tool ACLs (via tools[].access.acls), which travel with the tool definition when a listener aggregates it.

Using AI Consumers and Groups in ACLs

When access.acl_attribute_type is consumer, you can gate access by individual AI Consumers (using username, UUID, or custom ID) or by AI Consumer Group membership. This flexibility lets you define rules at the right level: deny a specific user, allow a tier-based group, or mix both in the same ACL. The runtime checks the authenticated AI Consumer’s identity and group memberships against your allow and deny lists.

How default and per-tool ACLs work

The runtime evaluates access using a two-tier system:

If a tool defines its own ACL, the runtime ignores access.default_tool_acls 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 access.default_tool_acls).

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 (HTTP 403 Forbidden).
2. Allow list configuration. If an allow list exists, the subject must match at least one entry; otherwise, the request is denied (HTTP 403 Forbidden).
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 audit log.

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

ACL tool control request flow

The runtime 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. The AI Auth Strategy validates the request and identifies the AI Consumer.
3. The runtime loads the AI Consumer’s group memberships.
4. The runtime evaluates each tool against default_tool_acls.
5. The runtime returns an HTTP 200 response with only the tools the AI Consumer is allowed to access.
6. The runtime logs the discovery attempt.

Tool invocation:

1. MCP client invokes a specific tool.
2. The AI Auth Strategy validates the request and identifies the AI Consumer.
3. The runtime loads the AI Consumer’s group memberships.
4. The runtime evaluates the tool-specific ACL if it exists, or the default ACL otherwise.
5. The runtime logs the access attempt (allowed or denied).
6. The runtime returns HTTP 403 Forbidden if denied, or forwards the request to the upstream MCP server if allowed.

 
sequenceDiagram
  participant Client as MCP Client
  participant Gateway as AI Gateway
  participant Auth as AI Auth Strategy
  participant ACL as AI MCP Server (ACL/Audit)
  participant Up as Upstream MCP Server
  participant Log as Audit Sink

  %% ----- List Tools -----
  rect
    note over Client,Gateway: List Tools (Default ACL Scope)
    Client->>Gateway: GET /tools
    Gateway->>Auth: Authenticate
    Auth-->>Gateway: Consumer identity
    Gateway->>ACL: Evaluate scoped default ACL
    ACL-->>Log: Audit entry
    alt If allowed
      Gateway-->>Client: Filtered tool list
    else If denied
      Gateway-->>Client: HTTP 403 Forbidden
    end
  end

  %% ----- Tool Invocation -----
  rect
    note over Client,Up: Tool Invocation (Per-tool ACL)
    Client->>Gateway: POST /tools/{tool}
    Gateway->>Auth: Authenticate
    Auth-->>Gateway: Consumer identity
    Gateway->>ACL: Evaluate per-tool ACL
    ACL-->>Log: Audit entry
    alt If allowed
      Gateway->>Up: Forward request
      Up-->>Gateway: Response
      Gateway-->>Client: Response
    else If denied
      Gateway-->>Client: HTTP 403 Forbidden
    end
  end
  

To monitor and troubleshoot MCP traffic, enable logging and audit trails through config.logging. You can capture per-request statistics for metrics, full request and response payloads for debugging, and audit entries for every ACL decision. Note that payload logging may expose sensitive data. Enable it only when debugging and be careful with retention. AI MCP Server analytics display in Konnect Explorer and Dashboards alongside other AI Gateway traffic, and export through OpenTelemetry.

The AI MCP Server runtime supports MCP operations and upstream interactions, while certain advanced features and non-HTTP protocols are not currently supported. The following table summarizes what is supported and what is outside the current scope.

The following example creates a conversion-listener AI MCP Server that exposes Swagger’s Petstore API through two MCP tools: get-pets-by-status and get-pet-by-id.

This example requires a local instance of the Petstore API. Start one with Docker:

docker run -d \
  --name swagger-petstore \
  -p 8080:8080 \
  swaggerapi/petstore3:latest

Copied!

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/mcp-servers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Petstore API",
      "name": "petstore-mcp",
      "type": "conversion-listener",
      "enabled": true,
      "policies": [],
      "access": {
        "acl_attribute_type": "consumer",
        "acls": {
          "allow": []
        },
        "default_tool_acls": {
          "deny": []
        }
      },
      "config": {
        "url": "http://host.docker.internal:8080/api/v3",
        "route": {
          "paths": [
            "/petstore"
          ]
        },
        "logging": {
          "payloads": false
        },
        "server": {
          "timeout": 60000
        }
      },
      "tools": [
        {
          "name": "get-pets-by-status",
          "description": "Find pets by status",
          "method": "GET",
          "path": "/petstore/pet/findByStatus",
          "parameters": [
            {
              "name": "status",
              "in": "query",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "available",
                  "pending",
                  "sold"
                ]
              },
              "description": "Status value to filter pets by"
            }
          ]
        },
        {
          "name": "get-pet-by-id",
          "description": "Get a pet by ID",
          "method": "GET",
          "path": "/petstore/pet/{petId}",
          "parameters": [
            {
              "name": "petId",
              "in": "path",
              "required": true,
              "schema": {
                "type": "integer"
              },
              "description": "ID of the pet to retrieve"
            }
          ]
        }
      ]
    }
    '

ai_gateway_mcp_servers:
  - ref: petstore-mcp
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Petstore API
    name: petstore-mcp
    type: conversion-listener
    enabled: true
    policies: []
    access:
      acl_attribute_type: consumer
      acls:
        allow: []
      default_tool_acls:
        deny: []
    config:
      url: http://host.docker.internal:8080/api/v3
      route:
        paths:
        - "/petstore"
      logging:
        payloads: false
      server:
        timeout: 60000
    tools:
    - name: get-pets-by-status
      description: Find pets by status
      method: GET
      path: "/petstore/pet/findByStatus"
      parameters:
      - name: status
        in: query
        required: true
        schema:
          type: string
          enum:
          - available
          - pending
          - sold
        description: Status value to filter pets by
    - name: get-pet-by-id
      description: Get a pet by ID
      method: GET
      path: "/petstore/pet/{petId}"
      parameters:
      - name: petId
        in: path
        required: true
        schema:
          type: integer
        description: ID of the pet to retrieve