# copilotkit/open-mcp-client architecture

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

- Interactive diagram: https://gitdiagram.com/copilotkit/open-mcp-client
- Repository: https://github.com/copilotkit/open-mcp-client

## Overview

- An “agent” service that lives in the /agent folder, which is a LangGraph agent written primarily in Python. Its purpose is to connect to MCP servers and trigger tool calls.
- A “frontend” service located in the /app folder, which is a Next.js-based application using CopilotKit to manage the UI and state synchronization.

a. Frontend Application (/app):
– Represented as a Next.js web application.
– Contains UI components (e.g., CopilotActionHandler, ExampleConfigs, MCPConfigForm, ToolCallRenderer), pages (page.tsx, layout.tsx), and custom hooks.
– Has an API route under app/api/copilotkit (route.ts) which might be supporting integration or proxying requests.

b. Agent Service (/agent):
– A LangGraph agent implemented in Python.
– Contains files like math_server.py, a sample agent module under sample_agent, and configuration files (e.g., langgraph.json, pyproject.toml).
– Responsible for connecting to MCP servers, likely using tools and commands outlined by LangGraph.

c. Shared/Support Libraries:
– Folder /lib contains utility functions (utils.ts) that may be reused by other parts of the system.
– Configuration files (.env in both the root and /agent, tsconfig.json, package.json, etc.) serve to configure both services and provide environmental settings.

d. External Services and Environment:
– External APIs such as OpenAI (provided via agent/.env API keys), MCP servers, and LangGraph endpoints.
– Environment configuration (via .env files) which supplies keys (LANGSMITH_API_KEY, OPENAI_API_KEY) needed for both frontend and agent services.

##### Relationships and Interactions
– Illustrate a possible API or messaging channel between the two. For instance, from the frontend’s API endpoints (the route.ts file inside app/api/copilotkit) to the Agent service.
– Indicate that user interactions in the frontend may trigger requests that eventually call upon the LangGraph agent to perform actions on remote MCP servers.

##### Architectural Patterns / Design Principles
– Emphasize the separation of concerns: the clear division between the frontend (UI and state management via CopilotKit and Next.js) and the backend agent that handles domain-specific logic (connecting to MCP servers).
– Note the modular design where each service can be developed, run, or debugged separately (as per the README’s instructions).
– Highlight that configuration management (through .env files) is central for secure API key management.

##### Technologies/Frameworks
– Frontend: Next.js, React components, CopilotKit.
– Agent: Python (with files such as math_server.py), LangGraph configuration (langgraph.json).
– General: TypeScript (as seen in tsconfig.json and *.ts/tsx files), package management using pnpm (pnpm-lock.yaml, package.json), and configuration files for ESLint, PostCSS, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User"]:::external

    subgraph "Frontend Application"
        FE["Frontend Application"]:::frontend
        F1["UI Components"]:::frontend
        F2["Pages & Layout"]:::frontend
        F3["Custom Hooks"]:::frontend
        F4["API Route for CopilotKit"]:::frontend
    end

    subgraph "Agent Service"
        AG["Agent Service"]:::agent
        A1["Main Execution & Tool Logic"]:::agent
        A2["Sample Agent Module"]:::agent
        A3["LangGraph Config"]:::agent
        A4["Python Project Config"]:::agent
    end

    subgraph "Shared/Support Libraries"
        S["Shared Libraries"]:::shared
    end

    subgraph "Environment Configurations"
        ENV["Environment Configurations (.env)"]:::config
    end

    subgraph "External Services"
        EX1["MCP Servers"]:::external
        EX2["OpenAI"]:::external
    end

    %% Connections
    U -->|"sends_request"| FE
    FE -->|"contains"| F1
    FE -->|"contains"| F2
    FE -->|"contains"| F3
    FE -->|"contains"| F4

    F4 -->|"calls_API"| A1
    A1 -->|"uses_module"| A2
    A1 -->|"reads_config"| A3
    A1 -->|"reads_config"| A4
    A1 -->|"triggers_tool_calls"| EX1
    A1 -->|"integrates_with"| EX2

    FE -->|"reads_env"| ENV
    AG -->|"reads_env"| ENV
    F1 -->|"uses"| S

    %% Click Events for Frontend
    click FE "https://github.com/copilotkit/open-mcp-client/tree/main/app"
    click F1 "https://github.com/copilotkit/open-mcp-client/tree/main/app/components"
    click F2 "https://github.com/copilotkit/open-mcp-client/blob/main/app/page.tsx"
    click F3 "https://github.com/copilotkit/open-mcp-client/tree/main/app/hooks"
    click F4 "https://github.com/copilotkit/open-mcp-client/blob/main/app/api/copilotkit/route.ts"

    %% Click Events for Agent
    click AG "https://github.com/copilotkit/open-mcp-client/tree/main/agent"
    click A1 "https://github.com/copilotkit/open-mcp-client/blob/main/agent/math_server.py"
    click A2 "https://github.com/copilotkit/open-mcp-client/tree/main/agent/sample_agent"
    click A3 "https://github.com/copilotkit/open-mcp-client/blob/main/agent/langgraph.json"
    click A4 "https://github.com/copilotkit/open-mcp-client/blob/main/agent/pyproject.toml"

    %% Click Event for Shared Library
    click S "https://github.com/copilotkit/open-mcp-client/blob/main/lib/utils.ts"

    %% Styles
    classDef frontend fill:#B3CDE0,stroke:#000,stroke-width:2px;
    classDef agent fill:#CDEBA0,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD580,stroke:#000,stroke-width:2px;
    classDef shared fill:#E4C1F9,stroke:#000,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#000,stroke-width:2px;
```
