# kong/mcp-konnect architecture

> Architecture diagram of the GitHub repository kong/mcp-konnect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kong/mcp-konnect
- Repository: https://github.com/kong/mcp-konnect

## Overview

##### Main Components
- MCP Server Entry Point: Represented by src/index.ts, which is the application’s main entry point.
- API Client: The src/api.ts component handles communication with the Kong Konnect API.
- Tool System: The src/tools.ts, src/parameters.ts, and src/prompts.ts files define and document the tools available for various operations.
- Operations Modules: The src/operations directory contains three key modules:
- analytics.ts – operations for querying API request analytics.
- configuration.ts – operations for retrieving gateway configuration data (services, routes, consumers, plugins).
- controlPlanes.ts – operations for managing and retrieving information about control planes.
- Common Types: src/types.ts holds shared type definitions across the project.
- External Dependencies: External integrations include environment-based configuration (via environment variables such as KONNECT_ACCESS_TOKEN and KONNECT_REGION) and the use of external AI assistants (e.g., Claude) which trigger the MCP tools.

##### Relationships and Interactions
- The MCP server uses the API client (api.ts) to communicate with Kong Konnect’s API endpoints.
- The tool system (tools.ts, prompts.ts, parameters.ts) serves to parse, validate, and document request parameters through Zod schemas and extend functionality.
- Direct the operations calls into three distinct modules in the operations folder: one for analytics, one for configuration, and one for control planes. These modules process the requests and return data to the request origin (either directly or via the AI client).
- External communication with Kong Konnect and also demonstrate integration with the client application (e.g., Claude for Desktop) as an external module that invokes the MCP server’s functionality via command-line Node.js execution.

##### Architectural Patterns and Key Technologies
- Separation of Concerns: Dividing the project into a main entry point, an API client, tool management, and operations modules reflects a clear separation of concerns.
- Modularity: Each operations module encapsulates a major functional area (analytics, configuration, control planes), making it easy to extend the toolset.
- Use of TypeScript: Ensuring type safety with shared type definitions.
- Configuration and Dependency Injection: Environment variables drive runtime configuration (e.g., API tokens, regions).
- Integration with AI assistants: The server is designed to be triggered by external tools like Claude, highlighting an external command execution pattern.

##### Final Advice for the Principal Software Engineer
- Component from the file structure is represented.
- Incorporate notes on the architectural patterns (such as separation of concerns and modularity) and specific technologies (TypeScript, Node.js, Zod schemas) to highlight the design intention.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    AIAssistant["AI Assistant (Claude)"]:::external
    KongAPI["Kong Konnect API"]:::external
    EnvConfig["Environment Variables (KONNECT_ACCESS_TOKEN, KONNECT_REGION)"]:::external

    %% Core Application Components
    MCPServer["MCP Server (index.ts)"]:::internal
    APIClient["Kong API Client (api.ts)"]:::internal
    SharedTypes["Shared Types (types.ts)"]:::internal

    %% Subgraph: Tool Definitions & Parameter Schemas
    subgraph "Tool Definitions & Parameter Schemas"
        Tools["Tools (tools.ts)"]:::internal
        Parameters["Parameters (parameters.ts)"]:::internal
        Prompts["Prompts (prompts.ts)"]:::internal
    end

    %% Subgraph: Operations Modules
    subgraph "Operations Modules"
        Analytics["Analytics (analytics.ts)"]:::internal
        Config["Configuration (configuration.ts)"]:::internal
        ControlPlanes["Control Planes (controlPlanes.ts)"]:::internal
    end

    %% Data Flow and Relationships
    AIAssistant -->|"triggers"| MCPServer
    MCPServer -->|"reads"| EnvConfig
    MCPServer -->|"initiates"| Tools
    MCPServer -->|"initiates"| Parameters
    MCPServer -->|"initiates"| Prompts
    MCPServer -->|"routes to"| Analytics
    MCPServer -->|"routes to"| Config
    MCPServer -->|"routes to"| ControlPlanes

    Tools -->|"guides"| Analytics
    Tools -->|"guides"| Config
    Tools -->|"guides"| ControlPlanes
    Parameters -->|"defines"| Analytics
    Parameters -->|"defines"| Config
    Parameters -->|"defines"| ControlPlanes
    Prompts -->|"provides"| Analytics
    Prompts -->|"provides"| Config
    Prompts -->|"provides"| ControlPlanes

    Analytics -->|"calls"| APIClient
    Config -->|"calls"| APIClient
    ControlPlanes -->|"calls"| APIClient
    APIClient -->|"queries"| KongAPI
    KongAPI -->|"responds to"| APIClient
    APIClient -->|"returns data to"| Analytics
    APIClient -->|"returns data to"| Config
    APIClient -->|"returns data to"| ControlPlanes

    Analytics -->|"uses"| SharedTypes
    Config -->|"uses"| SharedTypes
    ControlPlanes -->|"uses"| SharedTypes
    MCPServer -->|"uses"| SharedTypes

    %% Styles for clarity
    classDef internal fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD1A9,stroke:#333,stroke-width:2px;

    %% Click Events mapping to project file tree
    click MCPServer "https://github.com/kong/mcp-konnect/blob/main/src/index.ts"
    click APIClient "https://github.com/kong/mcp-konnect/blob/main/src/api.ts"
    click Tools "https://github.com/kong/mcp-konnect/blob/main/src/tools.ts"
    click Parameters "https://github.com/kong/mcp-konnect/blob/main/src/parameters.ts"
    click Prompts "https://github.com/kong/mcp-konnect/blob/main/src/prompts.ts"
    click Analytics "https://github.com/kong/mcp-konnect/blob/main/src/operations/analytics.ts"
    click Config "https://github.com/kong/mcp-konnect/blob/main/src/operations/configuration.ts"
    click ControlPlanes "https://github.com/kong/mcp-konnect/blob/main/src/operations/controlPlanes.ts"
    click SharedTypes "https://github.com/kong/mcp-konnect/blob/main/src/types.ts"
```
