How aipoweryou94/llamacloud-mcp works
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)