npx -y @modelcontextprotocol/inspector@0.22.0 --cli \
http://localhost:8000/mcp-aggregation \
--transport http --method tools/list | jq -r '.tools[].name'Aggregate MCP tools from multiple AI MCP Server entities
Incompatible with
on-prem
Related Documentation
Related Resources
Minimum Version
AI Gateway - 2.0
TL;DR
Aggregating MCP tools lets an MCP client call tools from several backend APIs without connecting to each one separately.
To aggregate MCP tools, create one AI MCP Server entity per REST API in conversion-only mode.
Then, create a listener AI MCP Server and list the MCP servers as sources.
The listener merges every matching source’s tools into a single MCP endpoint and routes each tool call to the correct backend.
This tutorial shows you how to aggregate tools from a mock Petstore API and the Deck of Cards API using kongctl, and validate the aggregated endpoint.
Prerequisites
AI Gateway running
This is a Konnect tutorial and requires a Konnect personal access token.
-
Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
-
Export your token to an environment variable:
export KONNECT_TOKEN='YOUR_KONNECT_PAT' -
Run the AI Gateway quickstart script to automatically provision a control plane and data plane in Kong Konnect, and configure your environment:
curl -Ls https://get.konghq.com/ai | bash -s -- -k $KONNECT_TOKEN
This sets up a AI Gateway control plane named ai-quickstart, provisions a local data plane, and prints out the following environment variables export:
export AI_GATEWAY_ID=your-gateway-id
export KONNECT_TOKEN=$KONNECT_TOKEN
export KONNECT_CONTROL_PLANE_NAME=ai-quickstart
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'Copy and paste these into your terminal to configure your session.
kongctl v1.13.0+
This tutorial uses kongctl to manage Konnect resources programmatically. We recommend keeping kongctl up to date with the latest version (1.13.0).
- Install kongctl from developer.konghq.com/kongctl.
-
Verify the installation:
kongctl version
Petstore API
This tutorial uses Swagger’s Petstore API, run the following command to start the server:
docker run -d \
--name swagger-petstore \
-p 8080:8080 \
swaggerapi/petstore3:latestConvert the Deck of Cards API to MCP tools
Create an AI MCP Server entity in conversion-only mode for the Deck of Cards API, which needs no credentials.
kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" << 'EOF'
ai_gateway_mcp_servers:
- ref: cards-mcp
ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
name: cards-mcp
display_name: "Deck of Cards"
type: conversion-only
enabled: true
config:
url: https://deckofcardsapi.com
route:
paths:
- /api/deck
strip_path: false
tools:
- name: shuffle-cards
description: Shuffle a new deck of cards. Returns a deck_id to use with draw-cards.
method: GET
path: /api/deck/new/shuffle/
parameters:
- name: deck_count
in: query
required: false
schema:
type: integer
default: 1
description: Number of decks to use (default 1, blackjack typically uses 6)
- name: draw-cards
description: Draw cards from an existing deck. Requires a deck_id from shuffle-cards.
method: GET
path: "/api/deck/{deck_id}/draw/"
parameters:
- name: deck_id
in: path
required: true
schema:
type: string
description: Deck ID returned from shuffle-cards
- name: count
in: query
required: true
schema:
type: integer
default: 1
description: Number of cards to draw
- name: new-deck
description: Create a new deck.
method: GET
path: /api/deck/new/
EOFConvert the Petstore API to MCP tools
Create a second AI MCP Server entity in conversion-only mode for the mock Petstore API.
kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" << 'EOF'
ai_gateway_mcp_servers:
- ref: petstore-mcp
ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
name: petstore-mcp
display_name: "Petstore API"
type: conversion-only
enabled: true
policies: []
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:
- description: ID of the pet to retrieve
in: path
name: petId
required: true
schema:
type: integer
EOFAggregate the MCP tools
Create a third AI MCP Server entity in listener mode. Its sources field lists the MCP servers to aggregate, so the listener discovers them, merges their tools into a single list, and exposes them through one MCP endpoint.
kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" << 'EOF'
ai_gateway_mcp_servers:
- ref: mcp-aggregation
ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
name: mcp-aggregation
display_name: "Aggregated MCP tools"
type: listener
config:
route:
paths:
- /mcp-aggregation
sources:
- cards-mcp
- petstore-mcp
EOFVerify that the aggregated endpoint is configured with the MCP tools
You should see the following output:
draw-cards
get-pet-by-id
get-pets-by-status
shuffle-and-draw
shuffle-cardsValidate the aggregated tools
You can now test tools from each source through the aggregated endpoint.
Cleanup
Stop Petstore API
docker rm -f swagger-petstoreClean up AI Gateway resources
To clean up all AI Gateway resources created in this guide, run:
curl -Ls https://get.konghq.com/ai | bash -s -- -d