# aipoweryou94/llamacloud-mcp architecture

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

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

## Overview

1. How to run an MCP server (using both stdio and HTTP/SSE transports) that can integrate with tools like Claude Desktop.

##### Main components
- MCP Server Component: There are two server variants – one that communicates via stdio (mcp-server.py) and one over HTTP using SSE (mcp-http-server.py). Both instantiate a FastMCP instance with tool decorators.
- MCP Client Component: This is represented by mcp-client.py. It uses BasicMCPClient to connect to the MCP server for retrieving tool specifications and then forwarding queries.
- LlamaCloud Integration: The MCP server code (e.g., inside the tool function in mcp-server.py) creates a LlamaCloudIndex that queries data from LlamaCloud. This external service is integral to the retrieval-augmented generation (RAG) process.
- Claude Desktop Integration: The README provides instructions for configuring Claude Desktop to connect to the MCP server, which demonstrates how the server can be used by an external agent.
- Environment & Configuration: The system relies on environment variables (such as LLAMA_CLOUD_API_KEY and OPENAI_API_KEY) for key configurations. Also, files like pyproject.toml and claude_desktop_config.json hint at dependency management and external configuration.

##### Relationships/interactions between components
- The MCP Server “hosts” tools (defined via decorators) that internally query the LlamaCloud index. There is a clear data flow: a query is received → forwarded to LlamaCloud (using the RAG process) → response is sent back.
- The client (either Claude Desktop or an MCP client within LlamaIndex) connects to the MCP Server. In the HTTP scenario, the client interacts through a SSE endpoint (e.g., at http://localhost:8000/sse).

##### Architectural patterns and design principles
- Modular/Decoupled Architecture: There is a clear separation between the server logic (tool definitions and query handling) and the client logic (tool specification retrieval and agent orchestration).
- Decorator Pattern: Notice the use of the @mcp.tool() decorator for tool registration, indicating an extensible pattern for adding functionalities.
- Plug-and-Play Integration: Both Claude Desktop and LlamaIndex client integrations show how easily external agents can interact with MCP servers by consuming well-defined APIs/endpoints.
- Transport Abstraction: The server can be run with different transport modes (stdio for local desktop integration or HTTP/SSE for remote/agent-driven integration).

##### Relevant technologies, frameworks, and libraries
- Python as the primary language.
- LlamaIndex and LlamaCloud SDKs for index management and querying.
- FastMCP (presumably a custom or specialized module) for setting up the MCP server.
- Tools like Claude Desktop and OpenAI (if using the OpenAI API for conversation or query augmentation).
- Environment configuration is managed via a .env file.

- MCP Server (including two variants: standard and HTTP/SSE)
- Tool Registration/Handlers (showing the use of decorators and the query handling function, e.g., llama_index_documentation)
- MCP Client (located in mcp-client.py)
- External Services: LlamaCloud API/Index and OpenAI API
- Client Integration: Claude Desktop (with a note on configuration via claude_desktop_config.json)
- Query flow from client to server and from server to external APIs
- Response flows going back along the same paths
- Python-based server and client components versus external services
- Different transport channels (stdio vs. HTTP/SSE)

## Diagram (Mermaid)

```mermaid
graph TD
    Config["Configuration (pyproject.toml, Environment Variables)"]:::config
    Client["MCP Client (mcp-client.py)"]:::python
    Claude["Claude Desktop Integration (claude_desktop_config.json)"]:::python

    subgraph "MCP Server Components"
        ServerStdio["MCP Server (Stdio)"]:::python
        ServerHTTP["MCP Server (HTTP/SSE)"]:::python
        ToolHandlers["Tool Registration/Handlers (@mcp.tool)"]:::python
    end

    LlamaCloud["LlamaCloud API/Index"]:::external
    OpenAI["OpenAI API"]:::external

    Config -->|"sets-env"| ServerStdio
    Config -->|"sets-env"| ServerHTTP

    Client -->|"query-stdio"| ServerStdio
    Claude -->|"query-HTTP/SSE"| ServerHTTP

    ServerStdio -->|"registers-tools"| ToolHandlers
    ServerHTTP -->|"registers-tools"| ToolHandlers

    ToolHandlers -->|"query-RAG"| LlamaCloud
    LlamaCloud -->|"retrieval-response"| ToolHandlers

    ToolHandlers -->|"augment-query"| OpenAI
    OpenAI -->|"augmentation-response"| ToolHandlers

    ToolHandlers -->|"sends-response"| ServerStdio
    ToolHandlers -->|"sends-response"| ServerHTTP

    ServerStdio -->|"response-to-client"| Client
    ServerHTTP -->|"response-to-client"| Claude

    click ServerStdio "https://github.com/aipoweryou94/llamacloud-mcp/blob/main/mcp-server.py"
    click ServerHTTP "https://github.com/aipoweryou94/llamacloud-mcp/blob/main/mcp-http-server.py"
    click Client "https://github.com/aipoweryou94/llamacloud-mcp/blob/main/mcp-client.py"
    click Claude "https://github.com/aipoweryou94/llamacloud-mcp/blob/main/claude_desktop_config.json"
    click Config "https://github.com/aipoweryou94/llamacloud-mcp/blob/main/pyproject.toml"

    classDef python fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef external fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
