From 1be8aeabc95690b04ae2fbc52656eef8b6d2ad48 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Tue, 4 Aug 2026 11:02:43 +0200 Subject: [PATCH 1/2] Add how-to --- .../ai-gateway/aggregate-mcp-tools.md | 355 ++++++++++++++++++ .../v2/prereqs/marketplace-mock-api.md | 20 + 2 files changed, 375 insertions(+) create mode 100644 app/_how-tos/ai-gateway/aggregate-mcp-tools.md create mode 100644 app/_includes/md/ai-gateway/v2/prereqs/marketplace-mock-api.md diff --git a/app/_how-tos/ai-gateway/aggregate-mcp-tools.md b/app/_how-tos/ai-gateway/aggregate-mcp-tools.md new file mode 100644 index 0000000000..0d1b771acc --- /dev/null +++ b/app/_how-tos/ai-gateway/aggregate-mcp-tools.md @@ -0,0 +1,355 @@ +--- +title: Aggregate MCP tools from multiple AI MCP Server entities +content_type: how_to +related_resources: + - text: AI MCP Server entity + url: /ai-gateway/entities/ai-mcp-server/ + - text: Map a RESTful API to MCP tools + url: /ai-gateway/map-api-to-mcp-tools/ + - text: Map the WeatherAPI to an MCP Server + url: /ai-gateway/get-started-with-mcp-server/ + +description: Aggregate MCP tools from multiple RESTful APIs into a single MCP endpoint using AI MCP Server entities in conversion-only and listener modes + +products: + - ai-gateway + +permalink: /ai-gateway/aggregate-mcp-tools/ + +works_on: + - konnect + +min_version: + ai-gateway: '2.0' + +entities: + - ai-mcp-server + +tags: + - ai + - mcp + +tldr: + q: How do I aggregate MCP tools from multiple RESTful APIs into one MCP endpoint? + a: | + Create one [AI MCP Server](/ai-gateway/entities/ai-mcp-server/) entity per RESTful API in `conversion-only` mode, and give each the same `labels.ai-gateway-mcp-aggregation` value. Then create a `listener` AI MCP Server carrying the same label. It 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 marketplace API, WeatherAPI, and the Deck of Cards API using kongctl, and validate the aggregated endpoint with ChatWise. + +tools: + - kongctl + +prereqs: + inline: + - title: Mock marketplace API + include_content: md/ai-gateway/v2/prereqs/marketplace-mock-api + - title: WeatherAPI account + include_content: md/ai-gateway/v2/prereqs/weather-api + - title: OpenAI API key + content: | + This tutorial uses OpenAI: + + 1. [Create an OpenAI account](https://auth.openai.com/create-account). + 1. [Get an API key](https://platform.openai.com/api-keys). + icon_url: /assets/icons/openai.svg + - title: ChatWise desktop application + content: | + Download and install [ChatWise](https://chatwise.app/) for your OS. + + After installation: + 1. Launch the app. + 1. Navigate to the app's settings. + 1. Click **Providers** in the sidebar. + 1. In the Providers sidebar, click **OpenAI**. + 1. In the **API Key** field, enter your OpenAI API key. + +cleanup: + inline: + - title: Clean up {{site.ai_gateway}} resources + include_content: cleanup/products/ai-gateway + +--- + +## Convert the Deck of Cards API to MCP tools + +Create an [AI MCP Server](/ai-gateway/entities/ai-mcp-server/) entity in `conversion-only` mode for the [Deck of Cards API](https://deckofcardsapi.com/), which needs no credentials. Set `labels.ai-gateway-mcp-aggregation` so the listener you create later can discover it. + +{% entity_examples %} +ai_gateway_mcp_servers: + - ref: cards-mcp + ai_gateway: !lookup name:ai-quickstart + name: cards-mcp + display_name: "Deck of Cards" + type: conversion-only + enabled: true + labels: + ai-gateway-mcp-aggregation: payments + config: + url: https://deckofcardsapi.com + route: + paths: + - /cards-api-mcp + 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: shuffle-and-draw + description: Create a new shuffled deck and draw cards in one request. + method: GET + path: api/deck/new/draw/ + parameters: + - name: count + in: query + required: true + schema: + type: integer + default: 1 + description: Number of cards to draw +{% endentity_examples %} + +## Convert the marketplace API to MCP tools + +Create a second AI MCP Server entity in `conversion-only` mode for the mock marketplace API, tagged with the same `labels.ai-gateway-mcp-aggregation` value. + +{% entity_examples %} +ai_gateway_mcp_servers: + - ref: marketplace-mcp + ai_gateway: !lookup name:ai-quickstart + name: marketplace-mcp + display_name: "Marketplace API" + type: conversion-only + enabled: true + labels: + ai-gateway-mcp-aggregation: payments + config: + url: http://host.docker.internal:3000 + route: + paths: + - /marketplace + logging: + audits: true + tools: + - name: get-users + description: Get users + method: GET + path: /marketplace/users + parameters: + - name: id + in: query + required: false + schema: + type: string + description: Optional user ID + - name: get-orders-for-user + description: Get orders for a user + method: GET + path: /marketplace/orders + parameters: + - name: userid + in: query + required: true + schema: + type: string + description: User ID to filter orders +{% endentity_examples %} + +## Convert WeatherAPI to MCP tools + +Create a third AI MCP Server entity in `conversion-only` mode for [WeatherAPI](https://www.weatherapi.com/), tagged with the same `labels.ai-gateway-mcp-aggregation` value. + +{% entity_examples %} +ai_gateway_mcp_servers: + - ref: weather-mcp + ai_gateway: !lookup name:ai-quickstart + name: weather-mcp + display_name: "Weather API" + type: conversion-only + enabled: true + labels: + ai-gateway-mcp-aggregation: payments + config: + url: https://api.weatherapi.com/v1/current.json + route: + paths: + - /weather-internet-mcp + tools: + - name: weather-internet + description: Get current weather for a location + method: GET + query: + key: + - !env WEATHERAPI_API_KEY + parameters: + - name: q + in: query + required: true + schema: + type: string + default: London + description: Location query. Accepts US Zipcode, UK Postcode, Canada Postalcode, IP address, latitude/longitude, or city name. +{% endentity_examples %} + +## Aggregate the MCP tools + +Create a fourth AI MCP Server entity in `listener` mode. Its `config.server.label` points at the same `ai-gateway-mcp-aggregation: payments` label used on the three `conversion-only` entities, so the listener discovers them, merges their tools into a single list, and exposes them through one MCP endpoint. + +{% entity_examples %} +ai_gateway_mcp_servers: + - ref: mcp-aggregation + ai_gateway: !lookup name:ai-quickstart + name: mcp-aggregation + display_name: "Aggregated MCP tools" + type: listener + config: + route: + paths: + - /mcp-aggregation + server: + label: + ai-gateway-mcp-aggregation:payments +{% endentity_examples %} + +## Connect ChatWise to the aggregated endpoint + +1. In the ChatWise app, navigate to settings. +1. Click **MCP** in the sidebar. +1. Click the **+** button. +1. Select "HTTP Server (http)". +1. In the **Name** field, enter `mcp-aggregation`. +1. In the **URL** field, enter `http://localhost:8000/mcp-aggregation`. +1. Click **Verify (View Tools)** to confirm the connection. You should see the following tools listed: + - `get-users` + - `get-orders-for-user` + - `weather-internet` + - `shuffle-cards` + - `draw-cards` + - `shuffle-and-draw` +1. Close the settings window. + +## Validate the aggregated tools + +You can now test tools from each source through the single aggregated endpoint. + +1. In ChatWise, start a new chat. +1. Click the overflow (**...**) menu next to the chat input, then click the **hammer icon** to enable MCP tools. The icon turns blue when enabled. +1. From the hammer dropdown menu, enable `mcp-aggregation`. + +{% navtabs "validate-aggregated-mcp-tools" %} +{% navtab "Marketplace tools" %} + +Enter the following in the ChatWise chat: + +```text +What has Alice Johnson ordered? +``` + +ChatWise calls two tools exposed by the `marketplace-mcp` source in sequence: `get-users` to find Alice's ID, then `get-orders-for-user` to fetch her orders. Approve each tool call when prompted. + +When the agent finishes reasoning, you should see a response like the following: + +```text +To check Alice Johnson's orders, I need her user ID. Here's how we can proceed: + +Find Alice Johnson's ID: I'll first search for her user record to get the correct ID. +Fetch Orders: Once I have the ID, I'll retrieve her order history. +Let me start by searching for her user details. + +Alice Johnson's user ID is a1b2c3d4. Now, I'll retrieve her order history. + +a1b2c3d4 +Alice Johnson has placed the following orders: + +Sugar (50kg) +Cleaning Supplies Pack +Canned Tomatoes (100 cans) +``` +{:.no-copy-code} + +{% endnavtab %} +{% navtab "Weather tools" %} + +Enter the following in the ChatWise chat: + +```text +What is the current weather in Alexandria? +``` + +ChatWise calls the `weather-internet` tool exposed by the `weather-mcp` source. Approve the tool call when prompted: + +```text +> called weather-internet +``` +{:.no-copy-code} + +When the agent finishes reasoning, you should see a response like the following: + +```text +Alexandria, Egypt right now: + +- Temperature: 79°F (26.1°C), feels like 80°F (26.8°C) +- Condition: Sunny +- Wind: 7.4 mph NNW +- Humidity: 61% + +Warm and sunny with light NNW winds. +``` +{:.no-copy-code} + +{% endnavtab %} +{% navtab "Deck of Cards tools" %} + +Enter the following in the ChatWise chat: + +```text +Shuffle a new deck and draw 5 cards. +``` + +ChatWise calls the `shuffle-and-draw` tool exposed by the `cards-mcp` source. Approve the tool call when prompted: + +```text +> called shuffle-and-draw +``` +{:.no-copy-code} + +When the agent finishes reasoning, you should see a response like the following: + +```text +Here are your 5 cards: + +10 of Spades +Queen of Hearts +4 of Clubs +Ace of Diamonds +7 of Hearts +``` +{:.no-copy-code} + +{% endnavtab %} +{% endnavtabs %} diff --git a/app/_includes/md/ai-gateway/v2/prereqs/marketplace-mock-api.md b/app/_includes/md/ai-gateway/v2/prereqs/marketplace-mock-api.md new file mode 100644 index 0000000000..156d0945e2 --- /dev/null +++ b/app/_includes/md/ai-gateway/v2/prereqs/marketplace-mock-api.md @@ -0,0 +1,20 @@ +This tutorial uses a mock Express-based API that simulates a marketplace with users and their orders. It exposes `/marketplace/users` and `/marketplace/{userId}/orders` endpoints. + +Run the following to download and start the mock API: + +```sh +curl -s -o api.js "https://gist.githubusercontent.com/subnetmarco/5ddb23876f9ce7165df17f9216f75cce/raw/a44a947d69e6f597465050cc595b6abf4db2fbea/api.js" +npm install express +node api.js +``` + +Verify it's running: + +```sh +curl -X GET http://localhost:3000 +``` + +```text +{"name":"Sample Users API"}% +``` +{:.no-copy-code} From 2f5028e5e0c3aef827dbf6efdfbb4c5bd8a5fa9c Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Tue, 4 Aug 2026 13:04:17 +0200 Subject: [PATCH 2/2] fix --- app/_how-tos/ai-gateway/aggregate-mcp-tools.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/app/_how-tos/ai-gateway/aggregate-mcp-tools.md b/app/_how-tos/ai-gateway/aggregate-mcp-tools.md index 0d1b771acc..4b2a6e5be0 100644 --- a/app/_how-tos/ai-gateway/aggregate-mcp-tools.md +++ b/app/_how-tos/ai-gateway/aggregate-mcp-tools.md @@ -259,7 +259,8 @@ You can now test tools from each source through the single aggregated endpoint. 1. In ChatWise, start a new chat. 1. Click the overflow (**...**) menu next to the chat input, then click the **hammer icon** to enable MCP tools. The icon turns blue when enabled. -1. From the hammer dropdown menu, enable `mcp-aggregation`. +1. From the hammer dropdown menu, enable `mcp-aggregation`, you should see 6 tools associated with it. + {% navtabs "validate-aggregated-mcp-tools" %} {% navtab "Marketplace tools" %}