LlamaCloud MCP Server Managed Index Integration

Overview

The LlamaCloud MCP Server is a TypeScript-based Model Context Protocol (MCP) server that exposes one or more tools — each mapped to a separate managed index hosted on LlamaCloud. It runs as an MCP server process (stdio-based) so MCP-capable clients (for example Claude Desktop, Windsurf, Cursor, or other MCP clients) can load and call index-backed tools to query or retrieve documents without embedding index credentials in the client.

This server is useful when you want to centralize access to multiple LlamaCloud indexes, enforce a single API key on the server, and present simple, index-specific tool endpoints to an LLM agent. Each configured index becomes a dedicated tool with a query parameter and optional result-limiting configuration (topK).

Repository: https://github.com/run-llama/mcp-server-llamacloud

Features

• Create a separate MCP tool for every configured LlamaCloud managed index
• Per-tool query parameter to search the associated index
• Optional topK setting to limit returned results
• Auto-generated, human-readable tool names built from index names (e.g., get_information_<index_name>)
• Works with any MCP-compatible client via stdio
• Development helper scripts including a debugging Inspector

Installation / Configuration

Prerequisites:

• Node.js/npm
• A LlamaCloud API key

Install and run via npx (recommended for MCP client configs):

Example MCP client JSON config (typical for desktop MCP clients):

{
  "mcpServers": {
    "llamacloud": {
      "command": "npx",
      "args": [
        "-y",
        "@llamaindex/mcp-server-llamacloud",
        "--index",
        "10k-SEC-Tesla",
        "--description",
        "10k SEC documents from 2023 for Tesla",
        "--topK",
        "5",
        "--index",
        "10k-SEC-Apple",
        "--description",
        "10k SEC documents from 2023 for Apple"
      ],
      "env": {
        "LLAMA_CLOUD_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Environment variables:

• LLAMA_CLOUD_API_KEY (required): your LlamaCloud API key
• LLAMA_CLOUD_PROJECT_NAME (optional): defaults to Default if not provided

Command-line format when running manually:

npx @llamaindex/mcp-server-llamacloud \
  --index "10k-SEC-Tesla" --description "10k SEC documents from 2023 for Tesla" --topK 5 \
  --index "10k-SEC-Apple" --description "10k SEC documents from 2023 for Apple"

CLI option summary:

Available Tools / Resources

• One MCP tool per --index argument. Tool names follow the pattern get_information_<index_name> (index_name is derived from the supplied index string and sanitized for the tool name).
• Each tool accepts a query parameter (string) to perform searches against the linked LlamaCloud index.
• topK can be applied per-tool via the CLI to cap result counts.

Helpful resources:

• Project repository: https://github.com/run-llama/mcp-server-llamacloud
• MCP Inspector (for debugging MCP stdio): https://github.com/modelcontextprotocol/inspector

Development

Basic local development steps:

# Install deps
npm install

# Build
npm run build

# Watch (development auto-build)
npm run watch

To run the locally built server from your MCP client config, replace the npx command with:

"command": "node",
"args": ["./build/index.js", "--index", "YourIndex", "--description", "desc"]

Debugging:

• MCP servers communicate over stdio, which can make interactive debugging harder. Use the included MCP Inspector helper:

npm run inspector

The Inspector provides a web UI and intercepts stdio traffic so you can inspect MCP messages and tool calls during development.

Use Cases

• Query company filings: create an index per company (e.g., “10k-SEC-Tesla”) and add a tool that answers questions using the company’s filings. Example: ask the tool “What risk factors did Tesla list in the 2023 10-K?” and receive extracted passages or summarized findings limited by the tool’s topK.
• Multi-dataset agent: expose separate tools for different knowledge domains (product manuals, legal docs, customer chats). LLM agents can call the appropriate tool for the domain-specific lookup.
• Secure centralized access: clients don’t need direct LlamaCloud keys. The MCP server holds the API key and enforces which indexes are available to connected agents.
• Result control: configure per-index topK to trade off breadth vs latency (e.g., topK=3 for short summaries, topK=10 for research tasks).

Tips and Best Practices

• Name indexes clearly when passing --index and add meaningful --description text; those descriptions help humans and agents choose the correct tool.
• Use per-index topK to optimize performance and answer relevance.
• Keep the LLAMA_CLOUD_API_KEY secret and run the MCP server on trusted infrastructure.

For details, examples, and issues, see the GitHub repository: https://github.com/run-llama/mcp-server-llamacloud