# run-llama/llamacloud-mcp architecture

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

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

## Overview

This archived package exposes LlamaCloud index retrieval and file extraction as dynamically registered MCP tools. An operator configures indexes, extraction agents, IDs, API key, and transport through the CLI; an MCP client invokes the resulting tools and receives retrieved or extracted data. The sampled implementation is concentrated in `llamacloud_mcp/main.py`; the README documents supported transports and broader client usage, but those client examples are not repository modules.

Main entry points: [`llamacloud_mcp/main.py`](https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and MCP"]
  node_main["CLI Bootstrap<br/>[main.py]"]
  node_mcp["MCP Server<br/>[main.py]"]
end

subgraph group_retrieval["Index Retrieval"]
  node_index_tool["Index Tool<br/>[main.py]"]
  node_cloud_index["LlamaCloud Index"]
end

subgraph group_extraction["File Extraction"]
  node_extract_tool["Extract Tool<br/>[main.py]"]
  node_agent_api["Agent Listing API"]
  node_file_api["File Upload API"]
  node_job_api["Extraction Job API"]
end

node_operator(("Operator"))
node_client(("MCP Client"))

node_operator -->|"configures"| node_main
node_main -->|"registers tools"| node_mcp
node_main -->|"starts transport"| node_mcp
node_client -->|"invokes tools"| node_mcp
node_mcp -->|"dispatches query"| node_index_tool
node_mcp -->|"dispatches file"| node_extract_tool
node_index_tool -->|"retrieves nodes"| node_cloud_index
node_cloud_index -->|"returns results"| node_index_tool
node_extract_tool -->|"lists agents"| node_agent_api
node_extract_tool -->|"uploads file"| node_file_api
node_extract_tool -->|"starts extraction"| node_job_api
node_job_api -->|"returns data"| node_extract_tool
node_index_tool -->|"returns response"| node_mcp
node_extract_tool -->|"returns response"| node_mcp
node_mcp -->|"sends result"| node_client

click node_main "https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py"
click node_mcp "https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py"
click node_index_tool "https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py"
click node_extract_tool "https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_mcp,node_client toneBlue
class node_index_tool,node_cloud_index toneAmber
class node_extract_tool,node_agent_api,node_file_api,node_job_api toneMint
class node_operator toneIndigo
```

## Components

### CLI and MCP

- [CLI Bootstrap](https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py): `llamacloud_mcp/main.py`
- [MCP Server](https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py): `llamacloud_mcp/main.py`

### Index Retrieval

- [Index Tool](https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py): `llamacloud_mcp/main.py`
- **LlamaCloud Index**

### File Extraction

- [Extract Tool](https://github.com/run-llama/llamacloud-mcp/blob/main/llamacloud_mcp/main.py): `llamacloud_mcp/main.py`
- **Agent Listing API**
- **File Upload API**
- **Extraction Job API**

### Other components

- **Operator**
- **MCP Client**

## Connections

- Operator → CLI Bootstrap: configures
- CLI Bootstrap → MCP Server: registers tools
- CLI Bootstrap → MCP Server: starts transport
- MCP Client → MCP Server: invokes tools
- MCP Server → Index Tool: dispatches query
- MCP Server → Extract Tool: dispatches file
- Index Tool → LlamaCloud Index: retrieves nodes
- LlamaCloud Index → Index Tool: returns results
- Extract Tool → Agent Listing API: lists agents
- Extract Tool → File Upload API: uploads file
- Extract Tool → Extraction Job API: starts extraction
- Extraction Job API → Extract Tool: returns data
- Index Tool → MCP Server: returns response
- Extract Tool → MCP Server: returns response
- MCP Server → MCP Client: sends result