From 1334bb7f7adb07f6197c4eb57bd5788c9b44f0e6 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Thu, 21 May 2026 14:28:13 +0200 Subject: [PATCH 01/16] Add WIP landing page --- .github/styles/base/Kongterms.yml | 2 + .../context-mesh/context-mesh.yaml | 249 ++++++++++++++++++ .../images/konnect/context-mesh-terminal.svg | 61 +++++ app/assets/images/konnect/context-mesh.svg | 82 ++++++ jekyll.yml | 4 +- 5 files changed, 397 insertions(+), 1 deletion(-) create mode 100644 app/_landing_pages/context-mesh/context-mesh.yaml create mode 100644 app/assets/images/konnect/context-mesh-terminal.svg create mode 100644 app/assets/images/konnect/context-mesh.svg diff --git a/.github/styles/base/Kongterms.yml b/.github/styles/base/Kongterms.yml index ccb7d7af0e6..3959f6725e5 100644 --- a/.github/styles/base/Kongterms.yml +++ b/.github/styles/base/Kongterms.yml @@ -10,6 +10,8 @@ swap: Kong Gateway: "{{site.base_gateway}}" AI Gateway: "{{site.ai_gateway}}" Kong AI Gateway: "{{site.ai_gateway_name}}" + Kong Context Mesh: "{{site.context_mesh_product_name}}" + Context Mesh: "{{site.context_mesh}}" Kong Konnect: "{{site.konnect_product_name}}" Kong Ingress Controller: "{{site.kic_product_name}}" Kong Mesh: "{{site.mesh_product_name}}" diff --git a/app/_landing_pages/context-mesh/context-mesh.yaml b/app/_landing_pages/context-mesh/context-mesh.yaml new file mode 100644 index 00000000000..a547473278f --- /dev/null +++ b/app/_landing_pages/context-mesh/context-mesh.yaml @@ -0,0 +1,249 @@ +metadata: + title: "{{site.context_mesh}}" + content_type: landing_page + description: "Turn enterprise APIs into Code Mode MCP servers that AI agents can call directly." + products: + - konnect + breadcrumbs: + - /konnect/ + tags: + - ai + - mcp + search_aliases: + - agent context + - code mode mcp + +rows: + - header: + type: h1 + text: "Kong {{site.context_mesh}}" + sub_text: "Turn enterprise APIs into agent-ready MCP servers that AI agents can discover, call, and reason about." + + - columns: + - blocks: + - type: structured_text + config: + blocks: + - type: text + text: | + AI agents are only as good as the context they can reach. {{site.context_mesh}} exposes REST APIs to AI agents as Code Mode MCP servers. It is the mediation layer between agents and your APIs. Agent traffic to those APIs passes through the same path as the rest of your API traffic, so the policies and observability you already apply continue to apply. + + Agents cannot call most APIs directly. Each one requires either a custom SDK or prior training on that specific API, and neither approach scales when an organization runs dozens of internal APIs that change over time. {{site.context_mesh}} closes that gap. Given an OpenAPI specification, it produces an MCP server that agents call without per-agent integration code. + + {{site.context_mesh}} complements [AI Gateway](/ai-gateway/) by covering the other half of an agent's traffic. AI Gateway is the control layer between agents and LLMs. {{site.context_mesh}} is the mediation layer between agents and APIs. + + {:.success} + > {{site.context_mesh}} is in active development. The current release supports APIs as a source type. Additional source types are planned for future releases. + - blocks: + - type: image + config: + url: /assets/images/konnect/context-mesh.svg + alt_text: "{{site.context_mesh}} architecture diagram. AI agents connect through AI Gateway as the control layer for LLMs, and through {{site.context_mesh}} as the mediation layer for enterprise sources including APIs, data, docs, and code." + + - columns: + - blocks: + - type: structured_text + config: + header: + text: "Why {{site.context_mesh}}?" + blocks: + - type: text + text: | + {{site.context_mesh}} is designed to make enterprise APIs usable by AI agents without adding integration complexity to your teams. + + * **No per-agent integration code**: Generate the MCP server from an existing OpenAPI spec. The agent uses your API without anyone writing an SDK or per-agent glue. + * **One place to manage agent context**: Every MCP server you create is registered in {{site.konnect_product_name}} alongside the rest of your API infrastructure, not scattered across developer laptops. + * **Traffic stays on Kong**: Because each MCP server runs on a {{site.konnect_short_name}} control plane, agent calls to your APIs pass through Kong and can be governed with the policies you already use. + * **One agent, many APIs**: Connect an agent to several {{site.context_mesh}} MCP servers at once and let it decide which to call to complete a task. + + - columns: + - blocks: + - type: structured_text + config: + header: + text: "Code Mode MCP servers" + blocks: + - type: text + text: | + {{site.context_mesh}} generates MCP servers in [Code Mode](https://blog.cloudflare.com/code-mode/), a configuration that exposes an API as a single SDK-like interface rather than one tool per operation. + + A standard MCP server registers each API operation as a separate tool. For an API with dozens or hundreds of endpoints, the agent's tool list grows past what the model can reason about, and tool selection degrades. + + A Code Mode server exposes the API as a programmatic interface that the agent calls by writing short code snippets against it. The agent works at the SDK level instead of picking between many similar tools. This scales to large API surfaces without flooding the model's context, and lets an agent use your API without prior training on it. + - blocks: + - type: image + config: + url: /assets/images/konnect/context-mesh-terminal.svg + alt_text: "{{site.context_mesh}} terminal workflow example showing MCP server setup and usage." + + - header: + text: "Get started" + type: h2 + description: | + Walk through creating a Code Mode MCP server from an OpenAPI specification, deploying it, and calling it from an MCP client. + column_count: 2 + columns: + - blocks: + - type: card + config: + title: Create your first {{site.context_mesh}} MCP server + description: | + Step-by-step setup from OpenAPI spec to a working agent call. + cta: + text: "Get started" + url: "/konnect-platform/context-mesh/get-started/" + + - header: + text: "Connect an MCP client" + type: h2 + description: | + Once you've created a {{site.context_mesh}} MCP server, add its endpoint to your MCP client. Select your client below for setup instructions. + column_count: 3 + columns: + - blocks: + - type: card + config: + icon: /assets/icons/third-party/claude.svg + title: Claude Code CLI + description: | + Configure the MCP server using the `claude mcp add` command or by editing `~/.claude.json`. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#claude-code-cli" + - blocks: + - type: card + config: + icon: /assets/icons/vscode.svg + title: Visual Studio Code + description: | + Add MCP server configuration through VS Code's Command Palette and MCP settings. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#visual-studio-code" + - blocks: + - type: card + config: + icon: /assets/icons/cursor.svg + title: Cursor + description: | + Configure the MCP server in Cursor Settings under Tools & MCP. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#cursor" + - blocks: + - type: card + config: + icon: /assets/icons/github-copilot.svg + title: GitHub Copilot - VS Code + description: | + Set up the MCP server for the GitHub Copilot extension in Visual Studio Code. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#github-copilot-for-vs-code" + - blocks: + - type: card + config: + icon: /assets/icons/github-copilot.svg + title: GitHub Copilot - JetBrains + description: | + Configure the MCP server for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#github-copilot-for-jetbrains" + - blocks: + - type: card + config: + icon: /assets/icons/cog.svg + title: Other IDEs + description: | + Manual setup instructions for Windsurf, Eclipse, and other IDEs. + ctas: + - text: Installation guide + url: "/konnect-platform/context-mesh/installation/#other-ides" + + - header: + text: "Common usage patterns" + type: h2 + sub_text: | + End-to-end flows that combine a {{site.context_mesh}} server with one or more MCP clients. + columns: + - blocks: + - type: structured_text + config: + header: + text: "Pattern 1: Expose a single internal API" + blocks: + - type: text + text: | + Make one internal REST API callable by an AI agent. + - type: text + config: | + ```text + 1. Add the API's OpenAPI specification to the Konnect API catalog + → Or have the specification file ready for upload + + 2. In Konnect, open {{site.context_mesh}} > MCP Servers > New MCP Server + → Choose the source (catalog entry or uploaded spec) + → Name the server + → Select the target control plane + + 3. Wait for the server status to reach Healthy + → Copy the server's endpoint URL + + 4. Add the endpoint to your MCP client configuration + → Restart the client if required + + 5. Prompt the agent with a task that requires the API + → The agent discovers operations through Code Mode + → The agent calls the API directly + ``` + - blocks: + - type: structured_text + config: + header: + text: "Pattern 2: Compose multiple APIs in one workflow" + blocks: + - type: text + text: | + Let an agent combine data from several backend APIs in a single prompt. + - type: text + config: | + ```text + 1. For each API the agent will use: + a. Add or upload the OpenAPI specification + b. Create a Code Mode MCP server in {{site.context_mesh}} + c. Wait for Healthy status + d. Copy the endpoint URL + + 2. In your MCP client, add all server endpoints + → Each {{site.context_mesh}} server is a separate entry + + 3. Prompt the agent with a task that spans the APIs + → Example: "Find a destination with the best weather right + now and book me a window seat flight" + → The agent selects which servers to call and in what + order, based on the tools available + + 4. Review the agent's responses against the underlying + API responses to validate behavior + ``` + + - header: + text: "Frequently asked questions" + type: h2 + columns: + - blocks: + - type: faqs + config: + - q: How is {{site.context_mesh}} different from the Kong Konnect MCP Server? + a: | + The [{{site.konnect_product_name}} MCP Server](/konnect-platform/konnect-mcp/) exposes {{site.konnect_product_name}} itself, so you can manage Kong infrastructure from an AI assistant or IDE. {{site.context_mesh}} exposes your own backend APIs to AI agents as Code Mode MCP servers that run on Kong. + - q: Can I use {{site.context_mesh}} with non-API sources? + a: | + Not in the current release. The current release supports APIs through OpenAPI specifications. Additional source types are planned for future releases. + - q: Does {{site.context_mesh}} require AI Gateway? + a: | + No. {{site.context_mesh}} and AI Gateway are separate products. They cover complementary paths in an agent's connectivity, but neither depends on the other. + - q: Can I see traffic between my agents and the MCP servers? + a: | + [NEEDS INPUT: Confirm observability story. Likely uses standard {{site.konnect_short_name}} analytics on the host control plane, but specifics need verification before publishing.] diff --git a/app/assets/images/konnect/context-mesh-terminal.svg b/app/assets/images/konnect/context-mesh-terminal.svg new file mode 100644 index 00000000000..fbb928f6aa2 --- /dev/null +++ b/app/assets/images/konnect/context-mesh-terminal.svg @@ -0,0 +1,61 @@ + + + Claude Code terminal session calling an OpenWeather MCP server + A dark-mode terminal window showing Claude Code answering a weather question by calling the get_current_weather tool on an MCP server, returning conditions for San Francisco. + + + + + + + + + + + + + + + + + claude-code . zsh + + $ claude + + ● + Claude Code v1.4.2 + connected to 2 MCP servers: openweather, slack + + > + what's the weather in San Francisco right now? should I bring a jacket + to my 6pm meeting downtown? + + ⏺ + I'll check current conditions in San Francisco. + + + ▾ + openweather + · + get_current_weather + params + { city: "San Francisco", units: "imperial" } + result + { temp: 58, feels_like: 54, conditions: "Overcast", + wind: "12 mph WSW", humidity: 78, sunset: "18:42" } + + ⏺ + Currently 58°F in San Francisco, overcast, feeling closer to 54°F + with a 12 mph wind out of the west-southwest. Sunset is at 6:42 PM, + so it'll be cooling further during your meeting. + Yes, bring a jacket. A light layer would handle the temperature, + but the wind will make it feel sharper near the coast or in shaded + streets between buildings. + + + > + type a follow-up message + + + + \ No newline at end of file diff --git a/app/assets/images/konnect/context-mesh.svg b/app/assets/images/konnect/context-mesh.svg new file mode 100644 index 00000000000..72cb7b8ad6a --- /dev/null +++ b/app/assets/images/konnect/context-mesh.svg @@ -0,0 +1,82 @@ + + Context Mesh — the mediation layer between agents and enterprise context + + + + + + + + + + + + + CALLER + CONTROL + MEDIATION + SOURCES + + + + + + + + + + + + + + + + + + + AI agents + + + + + + LLMs + + + + + + AI Gateway + CONTROL LAYER + + + + + + + Context Mesh + MEDIATION LAYER + + + + + + + APIs + + + + Data + + + + Docs + + + + Code + + + + + \ No newline at end of file diff --git a/jekyll.yml b/jekyll.yml index d919adf270b..1ef812e1e98 100644 --- a/jekyll.yml +++ b/jekyll.yml @@ -128,6 +128,8 @@ ee_product_name: Kong Gateway Enterprise ee_product_name_official: Kong API Gateway Enterprise konnect_short_name: Konnect konnect_product_name: Kong Konnect +context_mesh: Context Mesh +context_mesh_product_name: Kong Context Mesh mesh_product_name: Kong Mesh kic_product_name: Kong Ingress Controller kic_product_name_short: KIC @@ -217,7 +219,7 @@ operator_kongroute_api_version: "v1alpha1" operator_kongcertificate_api_version: "v1alpha1" operator_kongreferencegrant_api_version: "v1alpha1" operator_kongpluginbinding_api_version: "v1alpha1" -gwapi_version: "1.4.1" +gwapi_version: "1.4.1" render_banner: false # Copy From 28ad15326a66506191ac871148774212db3a43f7 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Thu, 21 May 2026 16:02:23 +0200 Subject: [PATCH 02/16] Move landing page file --- app/_landing_pages/{context-mesh => }/context-mesh.yaml | 1 + 1 file changed, 1 insertion(+) rename app/_landing_pages/{context-mesh => }/context-mesh.yaml (99%) diff --git a/app/_landing_pages/context-mesh/context-mesh.yaml b/app/_landing_pages/context-mesh.yaml similarity index 99% rename from app/_landing_pages/context-mesh/context-mesh.yaml rename to app/_landing_pages/context-mesh.yaml index a547473278f..f5b9e2df873 100644 --- a/app/_landing_pages/context-mesh/context-mesh.yaml +++ b/app/_landing_pages/context-mesh.yaml @@ -4,6 +4,7 @@ metadata: description: "Turn enterprise APIs into Code Mode MCP servers that AI agents can call directly." products: - konnect + - ai-gateway breadcrumbs: - /konnect/ tags: From b40569583565fe9e15585c71bb2851b635f28860 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Thu, 28 May 2026 13:52:55 +0200 Subject: [PATCH 03/16] Add WIP how-tos --- .../get-started-with-context-mesh.md | 203 +++++++++++++ app/_landing_pages/context-mesh.yaml | 12 +- .../context-mesh/client-installation.md | 286 ++++++++++++++++++ 3 files changed, 495 insertions(+), 6 deletions(-) create mode 100644 app/_how-tos/context-mesh/get-started-with-context-mesh.md create mode 100644 app/konnect-platform/context-mesh/client-installation.md diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md new file mode 100644 index 00000000000..ff7e08c5374 --- /dev/null +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -0,0 +1,203 @@ +--- +title: "Deploy an MCP server with Context Mesh and Kong Operator" +permalink: /context-mesh/get-started-with-context-mesh/ +content_type: how_to +description: "Deploy a Context Mesh-backed MCP server from the Konnect UI onto an Operator-managed data plane" +breadcrumbs: + - /mcp/ + +products: + - gateway + - ai-gateway + +works_on: + - konnect + +min_version: + gateway: '3.13' + +plugins: + - ai-mcp-proxy + +entities: + - service + - route + - plugin + +tags: + - ai + - mcp + - kubernetes + +tldr: + q: "How do I deploy a Context Mesh MCP server from the Konnect UI?" + a: "Install the nightly {{site.kong_operator}} chart with the `mcp-server` feature gate, create a Konnect-managed `DataPlane`, then use the Konnect UI to create an MCP server against that control plane." + +tools: + - kubectl + - helm + +related_resources: + - text: "{{site.ai_gateway}}" + url: /ai-gateway/ + - text: AI MCP Proxy + url: /plugins/ai-mcp-proxy/ + +cleanup: + inline: + - title: Clean up Konnect environment + include_content: cleanup/platform/konnect + icon_url: /assets/icons/gateway.svg +--- + +{:.warning} +> Context Mesh and the `mcp-server` feature gate are currently available only in nightly builds of {{site.kong_operator}}. Do not use this setup in production. + +## Install {{site.kong_operator}} + +Look up a current nightly tag from the [`kong/nightly-kong-operator`](https://hub.docker.com/r/kong/nightly-kong-operator/tags) Docker Hub page. The version string below is an example and changes daily. + +```shell +helm upgrade --install kong-operator \ + oci://registry-1.docker.io/kong/nightly-kong-operator-chart \ + --version 0.0.0-nightly.20260505.sha.26d3afa \ + --set image.repository=kong/nightly-kong-operator \ + --set image.tag=sha-26d3afa \ + --set env.FEATURE_GATES=mcp-server \ + --set env.ENABLE_CONTROLLER_KONNECT=true \ + --create-namespace \ + --namespace kong-system +``` + +Confirm the Operator pod is running: + +```shell +kubectl get pods -n kong-system +``` + +## Create the Konnect-managed control plane and data plane + +Apply the manifest below. It creates a `KonnectAPIAuthConfiguration` holding your token, a `KonnectGatewayControlPlane` that the Operator mirrors into {{site.konnect_short_name}}, a `KonnectExtension` linking the data plane to that control plane, and a `DataPlane` running three {{site.base_gateway}} replicas. + +```shell +kubectl apply -f - < For the EU or AU {{site.konnect_short_name}} region, set `serverURL` to `eu.api.konghq.com` or `au.api.konghq.com`. + +Wait for the data plane to reach `Ready`: + +```shell +kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready +``` + +## Create the OpenWeather MCP server + +This example uses the public OpenWeather API. You need an OpenWeather API key and the OpenWeather OpenAPI spec. + +1. Create an account and API key at [openweathermap.org](https://home.openweathermap.org/users/sign_in). The key can take several hours to activate. +1. Download `openweathermap.json` from the Context Mesh API testing assets. + + {:.info} + > Check internally for the current location of this file. + +1. In {{site.konnect_short_name}}, go to **MCP Servers** and select **Create new MCP server**. +1. Name the server `openweather-service`. +1. Under **Add existing API**, open the **Upload new** tab and upload `openweathermap.json`. +1. Select the same Operator-managed control plane (`context-mesh-demo`). +1. Submit and wait for the server status to become **Healthy**. + +The MCP runtime is exposed at `/mcp/openweather-service`. + +### Connect an agent to the OpenWeather MCP server + +1. Export your OpenWeather API key: + + ```shell + export OPENWEATHERMAP_API_KEY= + ``` + +1. Follow the [client installation guide](/context-mesh/client-installation/) for your MCP client, using: + - **Server name**: `context-mesh-weather` + - **Server URL**: `http://localhost/mcp/openweather-service` + - **Header**: `X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}` + +1. Try a prompt: + + ``` + Tell me the weather in Hawaii. + ``` + {:.no-copy-code} + +## Undeploy the MCP servers + +To remove an MCP server, open it in the {{site.konnect_short_name}} UI and undeploy it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. + +To tear down the cluster-side resources: + +```shell +kubectl delete dataplane dataplane -n default +kubectl delete konnectextension my-konnect-config -n default +kubectl delete konnectgatewaycontrolplane test -n default +kubectl delete konnectapiauthconfiguration konnect-api-auth -n default +helm uninstall kong-operator -n kong-system +kubectl delete namespace kong-system +``` + +Deleting the `KonnectGatewayControlPlane` removes the control plane from {{site.konnect_short_name}} as well. \ No newline at end of file diff --git a/app/_landing_pages/context-mesh.yaml b/app/_landing_pages/context-mesh.yaml index f5b9e2df873..40f48ba5030 100644 --- a/app/_landing_pages/context-mesh.yaml +++ b/app/_landing_pages/context-mesh.yaml @@ -110,7 +110,7 @@ rows: Configure the MCP server using the `claude mcp add` command or by editing `~/.claude.json`. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#claude-code-cli" + url: "/context-mesh/client-installation/#claude-code-cli" - blocks: - type: card config: @@ -120,7 +120,7 @@ rows: Add MCP server configuration through VS Code's Command Palette and MCP settings. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#visual-studio-code" + url: "/context-mesh/client-installation/#visual-studio-code" - blocks: - type: card config: @@ -130,7 +130,7 @@ rows: Configure the MCP server in Cursor Settings under Tools & MCP. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#cursor" + url: "/context-mesh/client-installation/#cursor" - blocks: - type: card config: @@ -140,7 +140,7 @@ rows: Set up the MCP server for the GitHub Copilot extension in Visual Studio Code. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#github-copilot-for-vs-code" + url: "/context-mesh/client-installation/#github-copilot-for-vs-code" - blocks: - type: card config: @@ -150,7 +150,7 @@ rows: Configure the MCP server for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#github-copilot-for-jetbrains" + url: "/context-mesh/client-installation/#github-copilot-for-jetbrains" - blocks: - type: card config: @@ -160,7 +160,7 @@ rows: Manual setup instructions for Windsurf, Eclipse, and other IDEs. ctas: - text: Installation guide - url: "/konnect-platform/context-mesh/installation/#other-ides" + url: "/context-mesh/client-installation/#other-ides" - header: text: "Common usage patterns" diff --git a/app/konnect-platform/context-mesh/client-installation.md b/app/konnect-platform/context-mesh/client-installation.md new file mode 100644 index 00000000000..0e57b0c2591 --- /dev/null +++ b/app/konnect-platform/context-mesh/client-installation.md @@ -0,0 +1,286 @@ +--- +title: "Connect MCP clients to {{site.context_mesh}}" +description: "Configure MCP clients including Claude Code CLI, VS Code, Cursor, and GitHub Copilot to connect to your {{site.context_mesh}} servers." +content_type: reference +layout: reference +products: + - konnect + - ai-gateway +tags: + - ai + - mcp +works_on: + - konnect +breadcrumbs: + - /context-mesh/ +permalink: /context-mesh/client-installation/ + +related_resources: + - text: "Get started with {{site.context_mesh}}" + url: /context-mesh/get-started/ + - text: "{{site.context_mesh}}" + url: /context-mesh/ +--- + +Once you've created a {{site.context_mesh}} MCP server, configure your MCP client by adding the server endpoint and any required authentication headers. Replace the placeholders below with your server's actual URL and credentials. + +## Generic MCP client config + +For any standard MCP client, use this JSON configuration format: + +```json +{ + "mcpServers": { + "SERVER_NAME": { + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } +} +``` + +Replace: +- `SERVER_NAME` with your server's name (e.g., `flights_service`, `openweather-service`) +- `http://localhost/mcp/SERVER_PATH` with your server's endpoint URL +- `HEADER_NAME` and `ENV_VAR_NAME` with the authentication header required by your API + +## {{ site.claude_code }} CLI + +Using the `claude mcp add` command: + +```bash +claude mcp add --transport http SERVER_NAME \ + http://localhost/mcp/SERVER_PATH \ + --header "HEADER_NAME: ${ENV_VAR_NAME}" +``` + +Or edit `~/.claude.json` directly: + +```json +{ + "mcpServers": { + "SERVER_NAME": { + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } +} +``` + +**Verify the configuration** + +List all configured servers: + +```sh +claude mcp list +``` + +You should see your server listed with a status indicator. + +## Visual Studio Code + +1. Open Visual Studio Code +1. Open the Command Palette (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux) +1. Type "MCP" and select **MCP: Open User Configuration** +1. Add your {{site.context_mesh}} server configuration: + + ```json + { + "inputs": [ + { + "type": "promptString", + "id": "api_key", + "description": "API Key or Token", + "password": true + } + ], + "servers": { + "SERVER_NAME": { + "type": "http", + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${input:api_key}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save the configuration file +1. Reload VS Code (Command Palette > **Developer: Reload Window**) +1. When prompted, enter your API key or authentication token +1. Verify the server is running in the MCP settings + +{:.info} +> VS Code securely stores your credentials after the first prompt. + +## Cursor + +1. Open the Cursor desktop app +1. Navigate to **Cursor Settings** (gear icon in top right corner) +1. Select **MCP** from the left sidebar +1. Click **+ Add new global MCP server** +1. Paste the following JSON configuration: + + ```json + { + "mcpServers": { + "SERVER_NAME": { + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save the configuration file +1. Return to **Cursor Settings > MCP** and verify your server is listed +1. Press `Cmd+L` (Mac) or `Ctrl+L` (Windows/Linux) to open Cursor chat +1. Click `@` to add context and select tools from your {{site.context_mesh}} server + +## GitHub Copilot for VS Code + +1. Open Visual Studio Code +1. Ensure GitHub Copilot extension is installed +1. Open the Command Palette (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux) +1. Type "MCP" and select **MCP: Open User Configuration** +1. Add your {{site.context_mesh}} server configuration: + + ```json + { + "inputs": [ + { + "type": "promptString", + "id": "api_key", + "description": "API Key or Token", + "password": true + } + ], + "servers": { + "SERVER_NAME": { + "type": "http", + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${input:api_key}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save the configuration file +1. Reload VS Code (Command Palette > **Developer: Reload Window**) +1. When prompted, enter your API key +1. Open GitHub Copilot chat and verify your {{site.context_mesh}} tools are available + +{:.info} +> VS Code securely stores your credentials after the first prompt. + +## GitHub Copilot for JetBrains + +For IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs: + +1. Open your JetBrains IDE +1. Ensure GitHub Copilot plugin is installed (version 1.5.50 or later) +1. Click the **GitHub Copilot** icon in the toolbar +1. Select **Open Chat** +1. Switch to **Agent mode** in the chat panel +1. Click the **tools icon** (wrench/settings) +1. Select **Edit settings** to open MCP configuration +1. Add your {{site.context_mesh}} server configuration: + + ```json + { + "servers": { + "SERVER_NAME": { + "type": "http", + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save the configuration file +1. Restart your IDE +1. Open GitHub Copilot chat and verify your {{site.context_mesh}} tools are available + +## Windsurf + +1. Open Windsurf +1. Navigate to `~/.codeium/windsurf/` +1. Create or edit `mcp_config.json`: + + ```json + { + "mcpServers": { + "SERVER_NAME": { + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save the file +1. Restart Windsurf +1. Open Cascade chat and verify your {{site.context_mesh}} tools are available + +## Other IDEs + +For Eclipse, Xcode, and other IDEs with MCP or GitHub Copilot support: + +1. Locate your IDE's MCP or GitHub Copilot settings +1. Add your {{site.context_mesh}} server using the generic JSON format: + + ```json + { + "mcpServers": { + "SERVER_NAME": { + "url": "http://localhost/mcp/SERVER_PATH", + "headers": { + "HEADER_NAME": "${ENV_VAR_NAME}" + } + } + } + } + ``` + +1. Replace the placeholders with your server details +1. Save and restart your IDE +1. Verify your {{site.context_mesh}} tools are available in your AI assistant + +{:.info} +> Configuration methods vary by IDE. Consult your IDE's documentation for MCP server setup instructions. + +## Common headers + +Different APIs require different authentication headers. Check your API's requirements: + +| API | Header | Example | +|-----|--------|---------| +| Flights (KongAir) | `X-Upstream-Bearer-Token` | JWT token from KongAir | +| OpenWeather | `X-Upstream-Api-Key` | API key from OpenWeatherMap | +| Custom API | Depends on API | Consult API documentation | + +Export your credentials as environment variables before using the CLI or configuration files: + +```bash +export FLIGHTS_TOKEN= +export OPENWEATHERMAP_API_KEY= +``` From 21bdd1371a7617f79fe34a3d56837ae4a73c1bab Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Thu, 28 May 2026 13:56:42 +0200 Subject: [PATCH 04/16] fix links --- app/_landing_pages/context-mesh.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_landing_pages/context-mesh.yaml b/app/_landing_pages/context-mesh.yaml index 40f48ba5030..eb826a7f370 100644 --- a/app/_landing_pages/context-mesh.yaml +++ b/app/_landing_pages/context-mesh.yaml @@ -92,7 +92,7 @@ rows: Step-by-step setup from OpenAPI spec to a working agent call. cta: text: "Get started" - url: "/konnect-platform/context-mesh/get-started/" + url: "/context-mesh/get-started-with-context-mesh/" - header: text: "Connect an MCP client" From 213d4c7223491c6393d90c0e02027e17b8cb9014 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Thu, 28 May 2026 14:12:26 +0200 Subject: [PATCH 05/16] fix frontmatters --- .../context-mesh/get-started-with-context-mesh.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index ff7e08c5374..a0baafaac34 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -1,8 +1,8 @@ --- -title: "Deploy an MCP server with Context Mesh and Kong Operator" +title: "Deploy an MCP server with {{site.context_mesh}} and {{site.operator_product_name}}" permalink: /context-mesh/get-started-with-context-mesh/ content_type: how_to -description: "Deploy a Context Mesh-backed MCP server from the Konnect UI onto an Operator-managed data plane" +description: "Deploy a {{site.context_mesh}}-backed MCP server from the Konnect UI onto an Operator-managed data plane" breadcrumbs: - /mcp/ @@ -34,8 +34,7 @@ tldr: a: "Install the nightly {{site.kong_operator}} chart with the `mcp-server` feature gate, create a Konnect-managed `DataPlane`, then use the Konnect UI to create an MCP server against that control plane." tools: - - kubectl - - helm + - operator related_resources: - text: "{{site.ai_gateway}}" @@ -51,7 +50,7 @@ cleanup: --- {:.warning} -> Context Mesh and the `mcp-server` feature gate are currently available only in nightly builds of {{site.kong_operator}}. Do not use this setup in production. +> {{site.context_mesh}} and the `mcp-server` feature gate are currently available only in nightly builds of {{site.kong_operator}}. Do not use this setup in production. ## Install {{site.kong_operator}} @@ -147,7 +146,7 @@ Wait for the data plane to reach `Ready`: kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready ``` -## Create the OpenWeather MCP server +## Create the OpenWeather {{site.context_mesh}} server This example uses the public OpenWeather API. You need an OpenWeather API key and the OpenWeather OpenAPI spec. @@ -185,9 +184,9 @@ The MCP runtime is exposed at `/mcp/openweather-service`. ``` {:.no-copy-code} -## Undeploy the MCP servers +## Remove the MCP servers -To remove an MCP server, open it in the {{site.konnect_short_name}} UI and undeploy it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. +To remove an MCP server, open it in the {{site.konnect_short_name}} UI and delete it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. To tear down the cluster-side resources: From 3abd1765b5adfedab70b8b3d1f805c28a15290d3 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Fri, 29 May 2026 09:21:08 +0200 Subject: [PATCH 06/16] Update how to, add troubleshooting --- .../get-started-with-context-mesh.md | 558 ++++++++++++++++-- app/_landing_pages/context-mesh.yaml | 136 ++--- jekyll-dev.yml | 4 + 3 files changed, 593 insertions(+), 105 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index a0baafaac34..4c86b4a3c34 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -36,6 +36,365 @@ tldr: tools: - operator +prereqs: + inline: + - title: Claude code + content: | + Install [{{site.claude_code}}](https://claude.ai/code) for terminal access to the MCP server. + icon_url: /assets/icons/third-party/claude.svg + - title: Kubernetes cluster + content: | + Set up a local Kubernetes cluster using one of these options: + + **Kind** + + ```bash + kind create cluster --name context-mesh-demo + ``` + + **Minikube** + + ```bash + minikube start --cpus=4 --memory=8192 + ``` + + **Docker Desktop** + + 1. Open Docker Desktop preferences + 2. Go to **Kubernetes** tab + 3. Enable Kubernetes + 4. Wait for it to be ready (shows "Kubernetes is running") + icon_url: /assets/icons/kubernetes.svg + - title: OpenWeatherMap account + content: | + 1. Create an account at [openweathermap.org](https://home.openweathermap.org/users/sign_in) + 2. Generate an API key (may take several hours to activate) + + {% env_variables %} + OPENWEATHERMAP_API_KEY: + {% endenv_variables %} + - title: OpenWeather OpenAPI spec + content: | + Save the following as `openweathermap.json`: + + ```json + { + "openapi": "3.1.0", + "info": { + "title": "OpenWeatherMap One Call API", + "description": "Provides access to current weather, hourly forecast, and daily forecast data.", + "version": "v1.0.0" + }, + "servers": [ + { + "url": "https://api.openweathermap.org" + } + ], + "paths": { + "/data/2.5/weather": { + "get": { + "description": "Retrieve current weather, hourly forecast, and daily forecast based on latitude and longitude.", + "operationId": "getWeatherData", + "parameters": [ + { + "name": "lat", + "in": "query", + "required": true, + "description": "Latitude of the location.", + "schema": { + "type": "number" + } + }, + { + "name": "lon", + "in": "query", + "required": true, + "description": "Longitude of the location.", + "schema": { + "type": "number" + } + }, + { + "name": "appid", + "in": "query", + "required": true, + "description": "API key for authentication.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful response with weather data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WeatherResponse" + } + } + } + }, + "401": { + "description": "Unauthorized due to missing or invalid API key." + } + } + } + } + }, + "components": { + "securitySchemes": { + "apiKeyAuth": { + "type": "apiKey", + "in": "query", + "name": "appid" + } + }, + "schemas": { + "WeatherResponse": { + "type": "object", + "properties": { + "current": { + "type": "object", + "properties": { + "lat": { + "type": "number" + }, + "lon": { + "type": "number" + }, + "tz": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date" + }, + "units": { + "type": "string" + }, + "cloud_cover": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "humidity": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "precipitation": { + "type": "object", + "properties": { + "total": { + "type": "integer" + } + } + }, + "temperature": { + "type": "object", + "properties": { + "min": { "type": "number" }, + "max": { "type": "number" }, + "afternoon": { "type": "number" }, + "night": { "type": "number" }, + "evening": { "type": "number" }, + "morning": { "type": "number" } + } + }, + "pressure": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "wind": { + "type": "object", + "properties": { + "max": { + "type": "object", + "properties": { + "speed": { "type": "number" }, + "direction": { "type": "integer" } + } + } + } + } + } + }, + "hourly": { + "type": "array", + "items": { + "type": "object", + "properties": { + "lat": { + "type": "number" + }, + "lon": { + "type": "number" + }, + "tz": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date" + }, + "units": { + "type": "string" + }, + "cloud_cover": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "humidity": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "precipitation": { + "type": "object", + "properties": { + "total": { + "type": "integer" + } + } + }, + "temperature": { + "type": "object", + "properties": { + "min": { "type": "number" }, + "max": { "type": "number" }, + "afternoon": { "type": "number" }, + "night": { "type": "number" }, + "evening": { "type": "number" }, + "morning": { "type": "number" } + } + }, + "pressure": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "wind": { + "type": "object", + "properties": { + "max": { + "type": "object", + "properties": { + "speed": { "type": "number" }, + "direction": { "type": "integer" } + } + } + } + } + } + } + }, + "daily": { + "type": "array", + "items": { + "type": "object", + "properties": { + "lat": { + "type": "number" + }, + "lon": { + "type": "number" + }, + "tz": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date" + }, + "units": { + "type": "string" + }, + "cloud_cover": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "humidity": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "precipitation": { + "type": "object", + "properties": { + "total": { + "type": "integer" + } + } + }, + "temperature": { + "type": "object", + "properties": { + "min": { "type": "number" }, + "max": { "type": "number" }, + "afternoon": { "type": "number" }, + "night": { "type": "number" }, + "evening": { "type": "number" }, + "morning": { "type": "number" } + } + }, + "pressure": { + "type": "object", + "properties": { + "afternoon": { + "type": "integer" + } + } + }, + "wind": { + "type": "object", + "properties": { + "max": { + "type": "object", + "properties": { + "speed": { "type": "number" }, + "direction": { "type": "integer" } + } + } + } + } + } + } + } + } + } + } + } + } + ``` + {:.collapsible} related_resources: - text: "{{site.ai_gateway}}" url: /ai-gateway/ @@ -44,14 +403,30 @@ related_resources: cleanup: inline: + - title: Remove MCP server + content: | + To remove an MCP server, open it in the {{site.konnect_short_name}} UI and delete it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. + icon_url: /assets/icons/gateway.svg + - title: Clean up Kubernetes resources + content: | + To tear down the cluster-side resources: + + ```shell + kubectl delete dataplane dataplane -n default + kubectl delete konnectextension my-konnect-config -n default + kubectl delete konnectgatewaycontrolplane test -n default + kubectl delete konnectapiauthconfiguration konnect-api-auth -n default + helm uninstall kong-operator -n kong-system + kubectl delete namespace kong-system + ``` + + Deleting the `KonnectGatewayControlPlane` removes the control plane from {{site.konnect_short_name}} as well. + icon_url: /assets/icons/gateway.svg - title: Clean up Konnect environment include_content: cleanup/platform/konnect icon_url: /assets/icons/gateway.svg --- -{:.warning} -> {{site.context_mesh}} and the `mcp-server` feature gate are currently available only in nightly builds of {{site.kong_operator}}. Do not use this setup in production. - ## Install {{site.kong_operator}} Look up a current nightly tag from the [`kong/nightly-kong-operator`](https://hub.docker.com/r/kong/nightly-kong-operator/tags) Docker Hub page. The version string below is an example and changes daily. @@ -148,55 +523,162 @@ kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready ## Create the OpenWeather {{site.context_mesh}} server -This example uses the public OpenWeather API. You need an OpenWeather API key and the OpenWeather OpenAPI spec. +1. In {{site.konnect_short_name}}, go to **Context Mesh** > **MCP Servers** +1. Select **New MCP server**. +1. In the **Add a source** section, click the hyperlink to add a new source. +1. Select the **Upload new** tab and upload the `openweathermap.json`. +1. Click **Add Source**. +1. Select the OpenWeather API in the New MCP server wizard. +1. Click **Next**; +1. Name the server `openweather-service`. +1. Select the Operator-managed control plane (`context-mesh-demo`). +1. Click **Create server** and wait for the server status to become **Healthy**. -1. Create an account and API key at [openweathermap.org](https://home.openweathermap.org/users/sign_in). The key can take several hours to activate. -1. Download `openweathermap.json` from the Context Mesh API testing assets. +The MCP runtime is now exposed at `/mcp/openweather-service`. - {:.info} - > Check internally for the current location of this file. +## Connect an agent to the OpenWeather MCP server -1. In {{site.konnect_short_name}}, go to **MCP Servers** and select **Create new MCP server**. -1. Name the server `openweather-service`. -1. Under **Add existing API**, open the **Upload new** tab and upload `openweathermap.json`. -1. Select the same Operator-managed control plane (`context-mesh-demo`). -1. Submit and wait for the server status to become **Healthy**. +Add the MCP server to Claude Code using the CLI: -The MCP runtime is exposed at `/mcp/openweather-service`. +```bash +claude mcp add --transport http context-mesh-weather http://localhost:8080/mcp/openweather-service \ + --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" +``` -### Connect an agent to the OpenWeather MCP server +For other MCP clients (VS Code, Cursor, GitHub Copilot, etc.), see the [client installation guide](/context-mesh/client-installation/). -1. Export your OpenWeather API key: +Try a prompt in Claude Code: - ```shell - export OPENWEATHERMAP_API_KEY= - ``` +``` +Tell me the weather in Hawaii. +``` +{:.no-copy-code} -1. Follow the [client installation guide](/context-mesh/client-installation/) for your MCP client, using: - - **Server name**: `context-mesh-weather` - - **Server URL**: `http://localhost/mcp/openweather-service` - - **Header**: `X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}` +## Troubleshoot port forwarding -1. Try a prompt: +If you cannot access the MCP server at `http://localhost/mcp/openweather-service`, follow these steps to set up port forwarding directly to the MCP server. - ``` - Tell me the weather in Hawaii. - ``` - {:.no-copy-code} +### Verify the data plane is running + +Check that all three data plane pods are in `Running` status: + +```shell +kubectl get pods -n default +``` + +Expected output: + +``` +NAME READY STATUS RESTARTS AGE +dataplane-dataplane-dr7h6-566d4fc8f5-44ngp 1/1 Running 0 17h +dataplane-dataplane-dr7h6-566d4fc8f5-j4qtf 1/1 Running 0 17h +dataplane-dataplane-dr7h6-566d4fc8f5-v9wk4 1/1 Running 0 17h +``` + +{:.warning} +> If pods are in `Pending` or `CrashLoopBackOff` status, wait a few minutes or check the pod logs: `kubectl logs -n default ` + +### Check the MCP server service + +Verify the MCP server service is created and running: + +```shell +kubectl get svc -n default +``` + +Expected output: -## Remove the MCP servers +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +kubernetes ClusterIP 10.96.0.1 443/TCP 19h +mcpserver-test-45675cb3 ClusterIP 10.96.127.86 8080/TCP 57m +``` + +The MCP server service name is `mcpserver-test-45675cb3` and runs on port `8080`. -To remove an MCP server, open it in the {{site.konnect_short_name}} UI and delete it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. +### Set up port forwarding -To tear down the cluster-side resources: +Set up `kubectl` port forwarding to the MCP server service. This forwards local port 8080 to the MCP server: ```shell -kubectl delete dataplane dataplane -n default -kubectl delete konnectextension my-konnect-config -n default -kubectl delete konnectgatewaycontrolplane test -n default -kubectl delete konnectapiauthconfiguration konnect-api-auth -n default -helm uninstall kong-operator -n kong-system -kubectl delete namespace kong-system +kubectl port-forward svc/mcpserver-test-45675cb3 8080:8080 +``` + +Expected output: + +``` +Forwarding from 127.0.0.1:8080 -> 8080 +Forwarding from [::1]:8080 -> 8080 ``` -Deleting the `KonnectGatewayControlPlane` removes the control plane from {{site.konnect_short_name}} as well. \ No newline at end of file +{:.info} +> Run this command in a separate terminal and leave it running. The port forwarding must stay active while you use the MCP server. + +### Test the connection + +In another terminal, test that the MCP endpoint is now accessible: + +```shell +curl -i http://localhost:8080/ +``` + +Expected output when the server is ready: + +``` +HTTP/1.1 404 Not Found +date: Fri, 29 May 2026 04:46:25 GMT +server: uvicorn +content-length: 9 +content-type: text/plain; charset=utf-8 + +Not Found +``` + +{:.info} +> The `404` response is expected. It confirms the MCP server is accessible and running. + +### Register the MCP server with your client (alternative URL) + +Once port forwarding is active and the server is responding, register it with your {{site.context_mesh}} client using the direct port forwarding URL: + +```shell +claude mcp add --transport http context-mesh-weather http://localhost:8080 --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" +``` + +Expected output: + +``` +Added context-mesh-weather MCP server +``` + +If the server already exists, remove it first and re-add it: + +```shell +claude mcp remove context-mesh-weather +claude mcp add --transport http context-mesh-weather http://localhost:8080 --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" +``` + +### If port forwarding fails + +If you cannot establish port forwarding: + +1. Verify the MCP server pod is running: + + ```shell + kubectl get pods -n default | grep mcpserver + ``` + + Expected output: + + ``` + mcpserver-test-45675cb3-764b4d6d6c-q2gnp 1/1 Running 0 57m + ``` + +2. Check the pod logs for errors: + + ```shell + kubectl logs -n default mcpserver-test-45675cb3-764b4d6d6c-q2gnp + ``` + +3. If the pod is in `CrashLoopBackOff` or `Pending`, wait a few minutes for it to initialize. Then retry the port forwarding. + diff --git a/app/_landing_pages/context-mesh.yaml b/app/_landing_pages/context-mesh.yaml index eb826a7f370..2f729fe464c 100644 --- a/app/_landing_pages/context-mesh.yaml +++ b/app/_landing_pages/context-mesh.yaml @@ -71,6 +71,8 @@ rows: A standard MCP server registers each API operation as a separate tool. For an API with dozens or hundreds of endpoints, the agent's tool list grows past what the model can reason about, and tool selection degrades. A Code Mode server exposes the API as a programmatic interface that the agent calls by writing short code snippets against it. The agent works at the SDK level instead of picking between many similar tools. This scales to large API surfaces without flooding the model's context, and lets an agent use your API without prior training on it. + + Code Mode eliminates intermediate tool invocations by allowing agents to write and execute API calls as code. Instead of streaming every operation through the model, Code Mode returns only the final result to the context window. This reduces token consumption by **~99%** (from ~120,000 tokens to ~1,200 tokens) while maintaining full observability of the workflow. - blocks: - type: image config: @@ -94,73 +96,73 @@ rows: text: "Get started" url: "/context-mesh/get-started-with-context-mesh/" - - header: - text: "Connect an MCP client" - type: h2 - description: | - Once you've created a {{site.context_mesh}} MCP server, add its endpoint to your MCP client. Select your client below for setup instructions. - column_count: 3 - columns: - - blocks: - - type: card - config: - icon: /assets/icons/third-party/claude.svg - title: Claude Code CLI - description: | - Configure the MCP server using the `claude mcp add` command or by editing `~/.claude.json`. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#claude-code-cli" - - blocks: - - type: card - config: - icon: /assets/icons/vscode.svg - title: Visual Studio Code - description: | - Add MCP server configuration through VS Code's Command Palette and MCP settings. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#visual-studio-code" - - blocks: - - type: card - config: - icon: /assets/icons/cursor.svg - title: Cursor - description: | - Configure the MCP server in Cursor Settings under Tools & MCP. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#cursor" - - blocks: - - type: card - config: - icon: /assets/icons/github-copilot.svg - title: GitHub Copilot - VS Code - description: | - Set up the MCP server for the GitHub Copilot extension in Visual Studio Code. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#github-copilot-for-vs-code" - - blocks: - - type: card - config: - icon: /assets/icons/github-copilot.svg - title: GitHub Copilot - JetBrains - description: | - Configure the MCP server for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#github-copilot-for-jetbrains" - - blocks: - - type: card - config: - icon: /assets/icons/cog.svg - title: Other IDEs - description: | - Manual setup instructions for Windsurf, Eclipse, and other IDEs. - ctas: - - text: Installation guide - url: "/context-mesh/client-installation/#other-ides" + # - header: + # text: "Connect an MCP client" + # type: h2 + # description: | + # Once you've created a {{site.context_mesh}} MCP server, add its endpoint to your MCP client. Select your client below for setup instructions. + # column_count: 3 + # columns: + # - blocks: + # - type: card + # config: + # icon: /assets/icons/third-party/claude.svg + # title: Claude Code CLI + # description: | + # Configure the MCP server using the `claude mcp add` command or by editing `~/.claude.json`. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#claude-code-cli" + # - blocks: + # - type: card + # config: + # icon: /assets/icons/vscode.svg + # title: Visual Studio Code + # description: | + # Add MCP server configuration through VS Code's Command Palette and MCP settings. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#visual-studio-code" + # - blocks: + # - type: card + # config: + # icon: /assets/icons/cursor.svg + # title: Cursor + # description: | + # Configure the MCP server in Cursor Settings under Tools & MCP. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#cursor" + # - blocks: + # - type: card + # config: + # icon: /assets/icons/github-copilot.svg + # title: GitHub Copilot - VS Code + # description: | + # Set up the MCP server for the GitHub Copilot extension in Visual Studio Code. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#github-copilot-for-vs-code" + # - blocks: + # - type: card + # config: + # icon: /assets/icons/github-copilot.svg + # title: GitHub Copilot - JetBrains + # description: | + # Configure the MCP server for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#github-copilot-for-jetbrains" + # - blocks: + # - type: card + # config: + # icon: /assets/icons/cog.svg + # title: Other IDEs + # description: | + # Manual setup instructions for Windsurf, Eclipse, and other IDEs. + # ctas: + # - text: Installation guide + # url: "/context-mesh/client-installation/#other-ides" - header: text: "Common usage patterns" diff --git a/jekyll-dev.yml b/jekyll-dev.yml index 8304867177d..9a36d1a53ee 100644 --- a/jekyll-dev.yml +++ b/jekyll-dev.yml @@ -2,6 +2,10 @@ links: share: http://localhost:4000 web: http://localhost:4000 +# Site variables +context_mesh: Context Mesh +context_mesh_product_name: Kong Context Mesh + # skip generators to speed up dev builds, the name matches the generator's name skip: plugins: true # skip plugins generation, except for overviews From 932b64fd1f058c396967c5af244b86b25febadd8 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Fri, 29 May 2026 09:26:32 +0200 Subject: [PATCH 07/16] update how-to --- app/_how-tos/context-mesh/get-started-with-context-mesh.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 4c86b4a3c34..6b0fe6b864e 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -462,8 +462,8 @@ metadata: namespace: default spec: type: token - token: ${KPAT} - serverURL: us.api.konghq.com + token: ${KONNECT_TOKEN} + serverURL: us.api.konghq.tech --- kind: KonnectGatewayControlPlane apiVersion: konnect.konghq.com/v1alpha2 From 49fd847b7b22966864f77cc8825e632a984d5692 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Fri, 29 May 2026 09:35:40 +0200 Subject: [PATCH 08/16] appease vale --- .github/styles/base/Dictionary.txt | 1 + app/_how-tos/context-mesh/get-started-with-context-mesh.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/styles/base/Dictionary.txt b/.github/styles/base/Dictionary.txt index 049f335c2ed..1a6a822a0a1 100644 --- a/.github/styles/base/Dictionary.txt +++ b/.github/styles/base/Dictionary.txt @@ -831,6 +831,7 @@ service_name shm show_in_api Sigstore +sign_in slas Slowloris slsa diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 6b0fe6b864e..e94182bc8fb 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -30,7 +30,7 @@ tags: - kubernetes tldr: - q: "How do I deploy a Context Mesh MCP server from the Konnect UI?" + q: "How do I deploy a {{site.context_mesh}} MCP server from the Konnect UI?" a: "Install the nightly {{site.kong_operator}} chart with the `mcp-server` feature gate, create a Konnect-managed `DataPlane`, then use the Konnect UI to create an MCP server against that control plane." tools: @@ -523,7 +523,7 @@ kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready ## Create the OpenWeather {{site.context_mesh}} server -1. In {{site.konnect_short_name}}, go to **Context Mesh** > **MCP Servers** +1. In {{site.konnect_short_name}}, go to **{{site.context_mesh}}** > **MCP Servers** 1. Select **New MCP server**. 1. In the **Add a source** section, click the hyperlink to add a new source. 1. Select the **Upload new** tab and upload the `openweathermap.json`. From af025d53819a51e9fe2e78e6a15886b691c92348 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 1 Jun 2026 07:43:01 +0200 Subject: [PATCH 09/16] Update how-to guide --- .../get-started-with-context-mesh.md | 48 ++++++------------- 1 file changed, 15 insertions(+), 33 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index e94182bc8fb..67a17720e20 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -534,29 +534,11 @@ kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready 1. Select the Operator-managed control plane (`context-mesh-demo`). 1. Click **Create server** and wait for the server status to become **Healthy**. -The MCP runtime is now exposed at `/mcp/openweather-service`. +The MCP runtime is now exposed at `http://localhost:8080/mcp`. -## Connect an agent to the OpenWeather MCP server - -Add the MCP server to Claude Code using the CLI: - -```bash -claude mcp add --transport http context-mesh-weather http://localhost:8080/mcp/openweather-service \ - --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" -``` - -For other MCP clients (VS Code, Cursor, GitHub Copilot, etc.), see the [client installation guide](/context-mesh/client-installation/). +## Set up port forwarding -Try a prompt in Claude Code: - -``` -Tell me the weather in Hawaii. -``` -{:.no-copy-code} - -## Troubleshoot port forwarding - -If you cannot access the MCP server at `http://localhost/mcp/openweather-service`, follow these steps to set up port forwarding directly to the MCP server. +To access the MCP server locally, you need to set up port forwarding from your machine to the Kubernetes cluster. ### Verify the data plane is running @@ -619,7 +601,7 @@ Forwarding from [::1]:8080 -> 8080 In another terminal, test that the MCP endpoint is now accessible: ```shell -curl -i http://localhost:8080/ +curl -i http://localhost:8080/mcp ``` Expected output when the server is ready: @@ -637,12 +619,13 @@ Not Found {:.info} > The `404` response is expected. It confirms the MCP server is accessible and running. -### Register the MCP server with your client (alternative URL) +## Connect an agent to the OpenWeather MCP server -Once port forwarding is active and the server is responding, register it with your {{site.context_mesh}} client using the direct port forwarding URL: +Once port forwarding is active and the server is responding, register the MCP server with Claude Code: -```shell -claude mcp add --transport http context-mesh-weather http://localhost:8080 --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" +```bash +claude mcp add --transport http context-mesh-weather http://localhost:8080/mcp \ + --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" ``` Expected output: @@ -651,14 +634,14 @@ Expected output: Added context-mesh-weather MCP server ``` -If the server already exists, remove it first and re-add it: +Try a prompt in Claude Code: -```shell -claude mcp remove context-mesh-weather -claude mcp add --transport http context-mesh-weather http://localhost:8080 --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" ``` +Tell me the weather in Hawaii. +``` +{:.no-copy-code} -### If port forwarding fails +## Troubleshoot port forwarding If you cannot establish port forwarding: @@ -680,5 +663,4 @@ If you cannot establish port forwarding: kubectl logs -n default mcpserver-test-45675cb3-764b4d6d6c-q2gnp ``` -3. If the pod is in `CrashLoopBackOff` or `Pending`, wait a few minutes for it to initialize. Then retry the port forwarding. - +3. If the pod is in `CrashLoopBackOff` or `Pending`, wait a few minutes for it to initialize. Then retry the port forwarding. \ No newline at end of file From 894e3c4c55bfba08a3c65b396475ea45a0885bbb Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 1 Jun 2026 08:34:04 +0200 Subject: [PATCH 10/16] Add context mesh as a new product --- app/_data/products/context-mesh.yml | 2 ++ app/_data/schemas/frontmatter/base.json | 2 +- .../get-started-with-context-mesh.md | 1 + app/_indices/context-mesh.yaml | 19 +++++++++++++++++++ app/assets/icons/context-mesh.svg | 1 + 5 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 app/_data/products/context-mesh.yml create mode 100644 app/_indices/context-mesh.yaml create mode 100644 app/assets/icons/context-mesh.svg diff --git a/app/_data/products/context-mesh.yml b/app/_data/products/context-mesh.yml new file mode 100644 index 00000000000..12e8ecb52fe --- /dev/null +++ b/app/_data/products/context-mesh.yml @@ -0,0 +1,2 @@ +name: Context Mesh +icon: /assets/icons/context-mesh.svg diff --git a/app/_data/schemas/frontmatter/base.json b/app/_data/schemas/frontmatter/base.json index 754f9261f72..4d81ddb7678 100644 --- a/app/_data/schemas/frontmatter/base.json +++ b/app/_data/schemas/frontmatter/base.json @@ -43,7 +43,7 @@ "type": "array", "items": { "type": "string", - "enum": ["ai-gateway", "gateway", "insomnia", "mesh", "kic", "catalog", "observability", "dev-portal", "operator", "konnect", "event-gateway", "konnect-reference-platform", "metering-and-billing", "identity"] + "enum": ["ai-gateway", "gateway", "insomnia", "mesh", "kic", "catalog", "observability", "dev-portal", "operator", "konnect", "event-gateway", "konnect-reference-platform", "metering-and-billing", "identity", "context-mesh"] } }, "tools": { diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 67a17720e20..6d5e26ff5a8 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -7,6 +7,7 @@ breadcrumbs: - /mcp/ products: + - context-mesh - gateway - ai-gateway diff --git a/app/_indices/context-mesh.yaml b/app/_indices/context-mesh.yaml new file mode 100644 index 00000000000..4dbe2dcc59d --- /dev/null +++ b/app/_indices/context-mesh.yaml @@ -0,0 +1,19 @@ +title: "{{site.context_mesh}} Documentation" +description: Index containing all documentation for {{site.context_mesh}}. +sections: + - title: Overview + items: + - title: "{{site.context_mesh}} Overview" + description: Overview of {{site.context_mesh}} and how to expose REST APIs as Code Mode MCP servers + url: /context-mesh/ + - title: Get started with {{site.context_mesh}} + description: Deploy a {{site.context_mesh}}-backed MCP server from the Konnect UI onto an Operator-managed data plane + url: /context-mesh/get-started-with-context-mesh/ + - title: Connect MCP clients + description: Configure MCP clients to connect to {{site.context_mesh}} servers + url: /context-mesh/client-installation/ + - title: How-tos + items: + - type: how-to + products: + - context-mesh diff --git a/app/assets/icons/context-mesh.svg b/app/assets/icons/context-mesh.svg new file mode 100644 index 00000000000..03c7e7be930 --- /dev/null +++ b/app/assets/icons/context-mesh.svg @@ -0,0 +1 @@ + \ No newline at end of file From a2488c750272e8921b6d2f3e1485a31a912070a3 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 1 Jun 2026 10:02:28 +0200 Subject: [PATCH 11/16] fixes --- app/_landing_pages/context-mesh.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/app/_landing_pages/context-mesh.yaml b/app/_landing_pages/context-mesh.yaml index 2f729fe464c..306fdf1ef80 100644 --- a/app/_landing_pages/context-mesh.yaml +++ b/app/_landing_pages/context-mesh.yaml @@ -3,9 +3,10 @@ metadata: content_type: landing_page description: "Turn enterprise APIs into Code Mode MCP servers that AI agents can call directly." products: - - konnect + - context-mesh - ai-gateway breadcrumbs: + - /ai-gateway/ - /konnect/ tags: - ai From 6cfce5604ed89b5c73560b271bcc26c7e9480884 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 1 Jun 2026 10:26:06 +0200 Subject: [PATCH 12/16] fix styles --- app/_assets/stylesheets/index.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/_assets/stylesheets/index.css b/app/_assets/stylesheets/index.css index 0513ace4c9f..fbb31f4aeff 100644 --- a/app/_assets/stylesheets/index.css +++ b/app/_assets/stylesheets/index.css @@ -89,6 +89,8 @@ --color-observability-background: var(--color-semantic-yellow-secondary); --color-ai-gateway-brand: var(--color-semantic-green-primary); --color-ai-gateway-background: var(--color-semantic-green-secondary); + --color-context-mesh-brand: var(--color-semantic-green-primary); + --color-context-mesh-background: var(--color-semantic-green-secondary); --color-event-gateway-brand: var(--color-semantic-green-primary); --color-event-gateway-background: var(--color-semantic-green-secondary); --color-gateway-brand: var(--color-semantic-green-primary); From 4d920adf23dbd1df134de147736bdf58d732576e Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 1 Jun 2026 13:20:56 +0200 Subject: [PATCH 13/16] unpublish how-to --- app/_how-tos/context-mesh/get-started-with-context-mesh.md | 1 + 1 file changed, 1 insertion(+) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 6d5e26ff5a8..68f62833786 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -25,6 +25,7 @@ entities: - route - plugin +published: false tags: - ai - mcp From c78e5f19447d1741741877bcd93e45b1ebe95df7 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 10 Jun 2026 11:56:50 +0200 Subject: [PATCH 14/16] update get started guide --- .../context-mesh/get-started-with-context-mesh.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 68f62833786..44ca30996df 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -25,7 +25,7 @@ entities: - route - plugin -published: false +published: true tags: - ai - mcp @@ -431,14 +431,11 @@ cleanup: ## Install {{site.kong_operator}} -Look up a current nightly tag from the [`kong/nightly-kong-operator`](https://hub.docker.com/r/kong/nightly-kong-operator/tags) Docker Hub page. The version string below is an example and changes daily. - ```shell +helm repo update helm upgrade --install kong-operator \ - oci://registry-1.docker.io/kong/nightly-kong-operator-chart \ - --version 0.0.0-nightly.20260505.sha.26d3afa \ - --set image.repository=kong/nightly-kong-operator \ - --set image.tag=sha-26d3afa \ + kong/kong-operator \ + --set image.tag=2.2 \ --set env.FEATURE_GATES=mcp-server \ --set env.ENABLE_CONTROLLER_KONNECT=true \ --create-namespace \ From aeb64532a10666a760ca5be9d0af421f33e31548 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 10 Jun 2026 12:38:25 +0200 Subject: [PATCH 15/16] update getting started guide --- .../get-started-with-context-mesh.md | 200 +++--------------- 1 file changed, 35 insertions(+), 165 deletions(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index 44ca30996df..da5dc4c9139 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -2,7 +2,7 @@ title: "Deploy an MCP server with {{site.context_mesh}} and {{site.operator_product_name}}" permalink: /context-mesh/get-started-with-context-mesh/ content_type: how_to -description: "Deploy a {{site.context_mesh}}-backed MCP server from the Konnect UI onto an Operator-managed data plane" +description: "Deploy the OpenWeather {{site.context_mesh}} MCP server from the Konnect UI" breadcrumbs: - /mcp/ @@ -32,18 +32,21 @@ tags: - kubernetes tldr: - q: "How do I deploy a {{site.context_mesh}} MCP server from the Konnect UI?" - a: "Install the nightly {{site.kong_operator}} chart with the `mcp-server` feature gate, create a Konnect-managed `DataPlane`, then use the Konnect UI to create an MCP server against that control plane." + q: "How do I deploy the OpenWeather {{site.context_mesh}} MCP server?" + a: "Install {{site.kong_operator}} 2.2 with the `mcp-server` feature gate, create a Konnect-managed control plane and data plane, then create the MCP server from the Konnect UI." tools: - operator prereqs: inline: - - title: Claude code + - title: Konnect Personal Access Token content: | - Install [{{site.claude_code}}](https://claude.ai/code) for terminal access to the MCP server. - icon_url: /assets/icons/third-party/claude.svg + Generate a token in {{site.konnect_short_name}} and set the environment variable: + + {% env_variables %} + KONNECT_TOKEN: kpat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + {% endenv_variables %} - title: Kubernetes cluster content: | Set up a local Kubernetes cluster using one of these options: @@ -67,7 +70,11 @@ prereqs: 3. Enable Kubernetes 4. Wait for it to be ready (shows "Kubernetes is running") icon_url: /assets/icons/kubernetes.svg - - title: OpenWeatherMap account + - title: Claude Code + content: | + Install [{{site.claude_code}}](https://claude.ai/code) for terminal access to the MCP server. + icon_url: /assets/icons/third-party/claude.svg + - title: OpenWeatherMap account and API key content: | 1. Create an account at [openweathermap.org](https://home.openweathermap.org/users/sign_in) 2. Generate an API key (may take several hours to activate) @@ -397,42 +404,27 @@ prereqs: } ``` {:.collapsible} -related_resources: - - text: "{{site.ai_gateway}}" - url: /ai-gateway/ - - text: AI MCP Proxy - url: /plugins/ai-mcp-proxy/ cleanup: inline: - - title: Remove MCP server + - title: Undeploy the MCP server content: | - To remove an MCP server, open it in the {{site.konnect_short_name}} UI and delete it. This disassociates the MCP server from its control plane but keeps the {{site.konnect_short_name}} record. - icon_url: /assets/icons/gateway.svg - - title: Clean up Kubernetes resources - content: | - To tear down the cluster-side resources: - - ```shell - kubectl delete dataplane dataplane -n default - kubectl delete konnectextension my-konnect-config -n default - kubectl delete konnectgatewaycontrolplane test -n default - kubectl delete konnectapiauthconfiguration konnect-api-auth -n default - helm uninstall kong-operator -n kong-system - kubectl delete namespace kong-system - ``` - - Deleting the `KonnectGatewayControlPlane` removes the control plane from {{site.konnect_short_name}} as well. - icon_url: /assets/icons/gateway.svg - - title: Clean up Konnect environment - include_content: cleanup/platform/konnect + In the {{site.konnect_short_name}} UI, open the MCP server and delete it. This disassociates the MCP server from the control plane. icon_url: /assets/icons/gateway.svg --- -## Install {{site.kong_operator}} +## Update the Helm repository ```shell helm repo update +``` + +{:.info} +> This ensures you have the latest Kong Helm chart available locally. + +## Install {{site.kong_operator}} + +```shell helm upgrade --install kong-operator \ kong/kong-operator \ --set image.tag=2.2 \ @@ -442,15 +434,9 @@ helm upgrade --install kong-operator \ --namespace kong-system ``` -Confirm the Operator pod is running: +## Deploy Konnect-connected ControlPlane and DataPlane -```shell -kubectl get pods -n kong-system -``` - -## Create the Konnect-managed control plane and data plane - -Apply the manifest below. It creates a `KonnectAPIAuthConfiguration` holding your token, a `KonnectGatewayControlPlane` that the Operator mirrors into {{site.konnect_short_name}}, a `KonnectExtension` linking the data plane to that control plane, and a `DataPlane` running three {{site.base_gateway}} replicas. +Apply the manifest below: ```shell kubectl apply -f - < For the EU or AU {{site.konnect_short_name}} region, set `serverURL` to `eu.api.konghq.com` or `au.api.konghq.com`. - -Wait for the data plane to reach `Ready`: +## Wait for the DataPlane to be ready ```shell kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready @@ -528,138 +511,25 @@ kubectl wait --timeout=3m dataplane dataplane --for=condition=Ready 1. Select the **Upload new** tab and upload the `openweathermap.json`. 1. Click **Add Source**. 1. Select the OpenWeather API in the New MCP server wizard. -1. Click **Next**; +1. Click **Next**. 1. Name the server `openweather-service`. 1. Select the Operator-managed control plane (`context-mesh-demo`). 1. Click **Create server** and wait for the server status to become **Healthy**. -The MCP runtime is now exposed at `http://localhost:8080/mcp`. - -## Set up port forwarding - -To access the MCP server locally, you need to set up port forwarding from your machine to the Kubernetes cluster. - -### Verify the data plane is running - -Check that all three data plane pods are in `Running` status: - -```shell -kubectl get pods -n default -``` - -Expected output: - -``` -NAME READY STATUS RESTARTS AGE -dataplane-dataplane-dr7h6-566d4fc8f5-44ngp 1/1 Running 0 17h -dataplane-dataplane-dr7h6-566d4fc8f5-j4qtf 1/1 Running 0 17h -dataplane-dataplane-dr7h6-566d4fc8f5-v9wk4 1/1 Running 0 17h -``` - -{:.warning} -> If pods are in `Pending` or `CrashLoopBackOff` status, wait a few minutes or check the pod logs: `kubectl logs -n default ` - -### Check the MCP server service - -Verify the MCP server service is created and running: - -```shell -kubectl get svc -n default -``` - -Expected output: - -``` -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -kubernetes ClusterIP 10.96.0.1 443/TCP 19h -mcpserver-test-45675cb3 ClusterIP 10.96.127.86 8080/TCP 57m -``` +The MCP runtime is now exposed at `/mcp/openweather-service`. -The MCP server service name is `mcpserver-test-45675cb3` and runs on port `8080`. +## Test the OpenWeather MCP server -### Set up port forwarding - -Set up `kubectl` port forwarding to the MCP server service. This forwards local port 8080 to the MCP server: +Hook up the MCP server to an agent: ```shell -kubectl port-forward svc/mcpserver-test-45675cb3 8080:8080 -``` - -Expected output: - -``` -Forwarding from 127.0.0.1:8080 -> 8080 -Forwarding from [::1]:8080 -> 8080 -``` - -{:.info} -> Run this command in a separate terminal and leave it running. The port forwarding must stay active while you use the MCP server. - -### Test the connection - -In another terminal, test that the MCP endpoint is now accessible: - -```shell -curl -i http://localhost:8080/mcp -``` - -Expected output when the server is ready: - -``` -HTTP/1.1 404 Not Found -date: Fri, 29 May 2026 04:46:25 GMT -server: uvicorn -content-length: 9 -content-type: text/plain; charset=utf-8 - -Not Found -``` - -{:.info} -> The `404` response is expected. It confirms the MCP server is accessible and running. - -## Connect an agent to the OpenWeather MCP server - -Once port forwarding is active and the server is responding, register the MCP server with Claude Code: - -```bash -claude mcp add --transport http context-mesh-weather http://localhost:8080/mcp \ +claude mcp add --transport http context-mesh-weather http://localhost/mcp/openweather-service \ --header "X-Upstream-Api-Key: ${OPENWEATHERMAP_API_KEY}" ``` -Expected output: - -``` -Added context-mesh-weather MCP server -``` - Try a prompt in Claude Code: ``` Tell me the weather in Hawaii. ``` {:.no-copy-code} - -## Troubleshoot port forwarding - -If you cannot establish port forwarding: - -1. Verify the MCP server pod is running: - - ```shell - kubectl get pods -n default | grep mcpserver - ``` - - Expected output: - - ``` - mcpserver-test-45675cb3-764b4d6d6c-q2gnp 1/1 Running 0 57m - ``` - -2. Check the pod logs for errors: - - ```shell - kubectl logs -n default mcpserver-test-45675cb3-764b4d6d6c-q2gnp - ``` - -3. If the pod is in `CrashLoopBackOff` or `Pending`, wait a few minutes for it to initialize. Then retry the port forwarding. \ No newline at end of file From 238405aa098481e9414edb5ae9804f023f739f7c Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 10 Jun 2026 12:52:46 +0200 Subject: [PATCH 16/16] appease vale --- app/_how-tos/context-mesh/get-started-with-context-mesh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_how-tos/context-mesh/get-started-with-context-mesh.md b/app/_how-tos/context-mesh/get-started-with-context-mesh.md index da5dc4c9139..668e85b5d84 100644 --- a/app/_how-tos/context-mesh/get-started-with-context-mesh.md +++ b/app/_how-tos/context-mesh/get-started-with-context-mesh.md @@ -407,7 +407,7 @@ prereqs: cleanup: inline: - - title: Undeploy the MCP server + - title: Delete the MCP server content: | In the {{site.konnect_short_name}} UI, open the MCP server and delete it. This disassociates the MCP server from the control plane. icon_url: /assets/icons/gateway.svg