# mondaycom/mcp architecture

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

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

## Overview

##### Project type and purpose
- This is a monorepo containing two related npm packages:
- @mondaydotcomorg/monday-api-mcp: a CLI/server that implements the MCP (Model Context Protocol) to let AI agents talk to monday.com’s API.
- @mondaydotcomorg/agent-toolkit: a TypeScript toolkit for building AI agents that orchestrate monday.com operations (both standard and dynamic GraphQL tools).
- Its purpose is to provide an open-source framework for AI agent developers to integrate with monday.com: the MCP server acts as a protocol bridge, and the toolkit offers reusable tools, codegen, utilities, and test suites.

##### File structure
- Top-level config files (.eslintrc.json, prettier, GitHub workflows, turbo.json) show it uses Yarn/Turbo for monorepo builds and CI/CD for publishing and version checks.
- The packages directory holds two sub-packages:
- agent-toolkit: with codegen scripts, rollup bundler, GraphQL config, a src folder structured into core, mcp, monday-graphql, openai, utils, plus tests.
- monday-api-mcp: with a CLI entrypoint (src/index.ts), an args parser, utility modules under utils/args, and tests.
- Scripts and config (jest.config, tsconfig) indicate a TypeScript-first codebase, built into dist for publishing.
- README and docs folder contain usage/installation guides and version-bumping process.

##### README for additional insights
- The overview explains two main deliverables: the MCP server package and the Agent Toolkit package.
- It lists categories of “Available Tools” (Item Operations, Board Operations, Account Operations, WorkForms Operations) and “Dynamic API Tools.”
- It describes how to run the MCP server locally or point an MCP-compatible client (Claude Desktop, Cursor) to it.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Monorepo Config"
        CI["CI/CD Config"]:::infra
        ESLint["ESLint/Prettier Config"]:::infra
        Turbo["TurboRepo Config"]:::infra
    end

    subgraph "Packages"
        subgraph "monday-api-mcp (CLI Server)"
            MCP["MCP Server / CLI"]:::server
            ArgsParser["Args Parser"]:::server
            CliConfig["CLI Args Config & Types"]:::server
            MCPTests["Tests"]:::test
        end
        subgraph "agent-toolkit (Library)"
            Core["Core Modules"]:::library
            ToolsRegistry["Tool Definitions Registry"]:::library
            StdTools["Standard Platform API Tools"]:::library
            MondayApps["Monday Apps Tools"]:::library
            DynMgr["Dynamic Tool Manager"]:::library
            MCPToolkit["MCP Toolkit Integration"]:::library
            GraphQL["GraphQL Client & Generated Types"]:::library
            OpenAI["OpenAI Integration Layer"]:::library
            Utils["Utility Modules"]:::library
            BuildScripts["Build-time Codegen Scripts & Config"]:::infra
            ToolkitTests["Tests"]:::test
        end
    end

    Agent["AI Agent / MCP-Compatible Client"]:::external
    Graph["monday.com GraphQL API"]:::external
    GraphQLFetch["Schema Fetch Script"]:::infra
    CodegenCfg["Codegen & GraphQL Configs"]:::infra

    Agent -->|"JSON-RPC MCP requests"| MCP
    MCP -->|"parses args"| ArgsParser
    MCP -->|"uses registry"| ToolsRegistry
    ArgsParser -->|uses| CliConfig
    ToolsRegistry --> Core
    Core --> StdTools
    Core --> MondayApps
    MCP --> DynMgr
    MCP --> MCPToolkit
    MCPToolkit --> Core
    Core --> Utils
    Core --> OpenAI
    Core --> GraphQL
    StdTools --> GraphQL
    MondayApps --> GraphQL
    DynMgr --> GraphQL
    OpenAI --> GraphQL
    GraphQL -->|"GraphQL Queries"| Graph
    Graph -->|"Responses"| MCP
    MCP -->|"JSON-RPC responses"| Agent

    GraphQLFetch -.-> GraphQL
    CodegenCfg -.-> GraphQL
    BuildScripts -.-> GraphQL

    click MCP "https://github.com/mondaycom/mcp/blob/master/packages/monday-api-mcp/src/index.ts"
    click ArgsParser "https://github.com/mondaycom/mcp/blob/master/packages/monday-api-mcp/src/utils/args/args.service.ts"
    click CliConfig "https://github.com/mondaycom/mcp/blob/master/packages/monday-api-mcp/src/utils/args/args.config.ts"
    click MCPTests "https://github.com/mondaycom/mcp/blob/master/packages/monday-api-mcp/tests/mcp.test.ts"

    click Core "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/core/index.ts"
    click ToolsRegistry "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/core/tools/index.ts"
    click StdTools "https://github.com/mondaycom/mcp/tree/master/packages/agent-toolkit/src/core/tools/platform-api-tools"
    click MondayApps "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/core/tools/monday-apps-tools/index.ts"
    click DynMgr "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/mcp/dynamic-tool-manager.ts"
    click MCPToolkit "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/mcp/toolkit.ts"
    click GraphQL "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/monday-graphql/generated/graphql.ts"
    click OpenAI "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/openai/index.ts"
    click Utils "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/src/utils/index.ts"
    click BuildScripts "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/fetch-schema.sh"
    click ToolkitTests "https://github.com/mondaycom/mcp/blob/master/packages/agent-toolkit/tests/toolkit.test.ts"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef server fill:#bbf,stroke:#333,stroke-width:1px
    classDef library fill:#bfb,stroke:#333,stroke-width:1px
    classDef infra fill:#fbb,stroke:#333,stroke-width:1px
    classDef test fill:#ffb,stroke:#333,stroke-width:1px
```
