Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →To use an existing Model Context Protocol (MCP) server from a LlamaIndex agent, install llama-index-tools-mcp, connect with BasicMCPClient, convert the server’s tools with McpToolSpec, and pass them to a FunctionAgent. To expose a LlamaIndex workflow instead, use workflow_as_mcp. The first pattern consumes tools; the second publishes your workflow as an MCP app.
Choose whether LlamaIndex should consume or publish MCP tools
MCP is a protocol for making tools available to clients such as AI agents. In this integration, LlamaIndex can play either side of the connection:
- Consume: connect a LlamaIndex agent to an MCP server, retrieve its tools, and give the converted tools to the agent.
- Publish: wrap a LlamaIndex
Workflowas an MCP app withworkflow_as_mcp, so an MCP client can call it.
For most developers asking how to connect MCP tools to an agent, start with the consume path below. Choose the publish path when the workflow itself needs to be callable by other MCP-compatible clients. LlamaIndex documents both approaches in its MCP integration materials.
Install the MCP integration and model packages
Install the MCP integration, LlamaIndex, and the OpenAI LLM integration used in the example. Set an API key for the model provider before running the script.
python -m pip install llama-index llama-index-tools-mcp llama-index-llms-openaiThe package name for installation is llama-index-tools-mcp; in Python, its imports use llama_index.tools.mcp. The code below assumes that your MCP server is reachable at an HTTP URL ending in its MCP route. Replace the example address and tool names with the values for your server.
Connect an MCP server to a LlamaIndex FunctionAgent
This complete example connects over HTTP, restricts which server tools are exposed, and passes the resulting LlamaIndex tools to a FunctionAgent. The agent can then decide whether to call one of those tools in response to a user request.
import asyncio
import os
from llama_index.core.agent import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
async def main():
client = BasicMCPClient("https://example.com/mcp")
tool_spec = McpToolSpec(client=client)
# Restrict the tools available to this agent to the names you trust and need.
tools = await tool_spec.to_tool_list_async(
allowed_tools=["search", "fetch_record"]
)
agent = FunctionAgent(
llm=OpenAI(
model="gpt-4.1",
api_key=os.environ["OPENAI_API_KEY"],
),
tools=tools,
system_prompt=(
"You are an assistant with access to the supplied MCP tools. "
"Use them only when they help answer the user's request."
),
)
response = await agent.run(user_msg="Search for the latest record.")
print(response)
if __name__ == "__main__":
asyncio.run(main())Before running it, export OPENAI_API_KEY in your shell and replace https://example.com/mcp with the MCP server URL. The tool names in allowed_tools must match the names actually offered by the server; change them or omit the filter if your server uses different names. The server must be reachable from the machine running the Python process.
Fetch tools directly from a URL
If you only need the tools and do not need to keep a client object for additional configuration, LlamaIndex documents a helper that fetches tools from an MCP URL:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
from llama_index.tools.mcp import aget_tools_from_mcp_url
tools = await aget_tools_from_mcp_url(
"http://127.0.0.1:8000/mcp",
allowed_tools=["tool1", "tool2"],
)This snippet must run inside an asynchronous function, because the helper is awaited. Use the local address when the MCP server is running on the same host; use the address and transport route configured for your remote server otherwise.
What happens during conversion
McpToolSpec reads the MCP server’s available tools and turns them into LlamaIndex tools. The agent receives those converted tools, rather than speaking MCP directly during each model turn. The LlamaIndex agent handles tool selection and invocation through its regular tool interface. If a server publishes many tools, allowed_tools provides a useful governance boundary: expose only the names this agent should be able to call.
Configure transport and authentication
BasicMCPClient supports URL-based connections, including Streamable HTTP. The server and client need to agree on a reachable URL and compatible transport; a URL that points to a website homepage rather than the MCP route will not establish the intended connection.
Unauthenticated and token-protected servers
The minimal example leaves authentication out because the server may not require it. For a server requiring credentials, follow that server’s documented authentication mechanism and avoid putting secrets directly in source code or committing them to version control. The exact header, token, or credential setup depends on the MCP server; do not assume every server uses the same scheme.
OAuth
LlamaIndex documents OAuth setup through BasicMCPClient.with_oauth(...). Its inputs include a client name, redirect URIs, redirect and callback handlers, and optional token storage. If no custom storage is provided, the documented default stores tokens in memory. That default is convenient for a short-lived process, but it does not establish durable token persistence between restarts. Choose storage and redirect handling appropriate to your application’s deployment and security requirements.
Filter and govern the tools an agent can call
Tool exposure is a design decision, not just a convenience. An MCP server may offer capabilities that a particular agent should not use. Pass allowed_tools to to_tool_list_async() or aget_tools_from_mcp_url() to limit the resulting tool list. This controls which tools are supplied to that agent; it does not replace authorization checks performed by the MCP server itself.
- Use an explicit allowlist for agents with a narrow job, such as reading records but not changing them.
- Review the server’s actual tool names when an allowlist unexpectedly produces no usable tools.
- Keep server-side access controls in place for consequential operations. A tool omitted from one agent’s list may still be available to another client.
- Give the agent a system prompt that explains the intended use of its tools, but do not treat prompt text as a security boundary.
Publish a LlamaIndex Workflow as an MCP app
For the reverse direction, use workflow_as_mcp from llama_index.tools.mcp.utils. It adapts a LlamaIndex Workflow for MCP clients. The documented customization points include a workflow name and description, a start-event model, and additional arguments for the underlying FastMCP setup.
from llama_index.tools.mcp.utils import workflow_as_mcp
mcp_app = workflow_as_mcp(
workflow,
workflow_name="SupportWorkflow",
workflow_description="Handles support requests.",
)Here, workflow must be the LlamaIndex Workflow you have already constructed. This creates the MCP app object; deployment and serving are separate concerns, so use the serving approach required by your MCP runtime rather than assuming that creating the object starts a network server. When needed for the MCP CLI, install its documented extras with:
Free tools Windows power users keep installed
One-click scans. No signup required.
python -m pip install "mcp[cli]"If the workflow expects a particular input shape, configure the documented start_event_model to represent its starting event. Pass additional FastMCP constructor arguments only when your host setup requires them. Keep the workflow’s external dependencies, credentials, and authorization checks configured in the environment where the app will run.
Try the LlamaIndex-hosted documentation MCP endpoint
LlamaIndex provides a hosted documentation MCP endpoint at https://developers.llamaindex.ai/mcp. Its announced tools are search_docs, grep_docs, and read_doc, which can be wrapped with McpToolSpec and supplied to a FunctionAgent just like other MCP tools. This is a useful way to explore the integration against LlamaIndex documentation; it is distinct from connecting to a server you operate.
LlamaIndex also publishes the TypeScript package @llamaindex/llama-cloud-mcp. Its documented direct execution uses npx -y @llamaindex/llama-cloud-mcp and the LLAMA_CLOUD_API_KEY environment variable, and its README describes adding the server to MCP clients including Cursor, VS Code, and Claude Code. That package is a separate option from connecting a Python LlamaIndex agent to an arbitrary MCP server.
Or skip the browser setup
If the MCP task you want an agent to perform is capturing a webpage, ScreenshotNeo offers an MCP server for AI agents, alongside its screenshot API. The API example below makes a single GET request for a screenshot; see the ScreenshotNeo API documentation for request options. ScreenshotNeo’s MCP tools are take_screenshot, get_page_info, and capture_pdf.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorscurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.
Troubleshoot common integration failures
Connection or timeout errors
Check that the Python process can reach the exact MCP URL, that the server is running, and that the URL points to the MCP route rather than a general site page. For a local server, confirm its host, port, and route; for a remote endpoint, check any network rules between your process and the service.
No tools appear, or the agent cannot call the expected tool
Confirm that the server actually advertises the tool and that the spelling matches the allowed_tools entry. Temporarily remove the allowlist to distinguish a filtering mismatch from a discovery problem. Then inspect the returned tool list before constructing the agent.
Authentication or OAuth callback fails
Check the server’s required authentication method, configured redirect URI, and callback handling. For OAuth, ensure the client name and redirect URIs match the application setup. If an application expects tokens to survive a process restart, configure custom token storage instead of relying on the documented in-memory default.
Import or package errors
Install llama-index-tools-mcp in the same Python environment that runs the program. The distribution name contains hyphens, while the import path is llama_index.tools.mcp. If importing OpenAI fails in the example, install the separate llama-index-llms-openai integration package as shown above.
Workflow app is created but clients cannot connect
workflow_as_mcp adapts a workflow; it is not by itself proof that an MCP server is listening at a network address. Complete the serving and hosting configuration for your chosen runtime, then test its endpoint from the same network context as the intended client.
Reliability, latency, and operating cost
An MCP-backed agent introduces the model request, tool discovery or setup, a network call to the MCP server, and any work that server performs. Slow or unavailable services at either the model or tool layer can delay the final response. Keep operational timeouts appropriate to the tool’s task, report tool failures clearly, and test the complete path from agent to server rather than only testing the server in isolation.
For recurring processes, decide how the MCP connection and credentials are initialized, how OAuth tokens persist, and what happens when a server is unavailable. Restricting the tool list can also make the agent’s action surface easier to review. No performance benchmark or fixed runtime cost follows from the integration alone: actual latency and cost depend on the selected model, request pattern, server work, hosting, and provider pricing.
Recommended Free Tools
There are two independent cost surfaces: the model provider and the MCP server or service being called. LlamaIndex’s integration package does not establish a universal fee for MCP use; check the terms of the model and server you choose. Likewise, a locally hosted server and a hosted endpoint have different infrastructure and operational responsibilities.
Frequently Asked Questions
Can I use a local MCP server with LlamaIndex?
Yes. Use its reachable local MCP URL, such as a loopback address when the server runs on the same machine as the Python process.
Does LlamaIndex host an MCP server for its documentation?
Yes. The documented endpoint is https://developers.llamaindex.ai/mcp.
Can a LlamaIndex Workflow be called from non-LlamaIndex MCP clients?
Yes. The purpose of wrapping it with workflow_as_mcp is to expose it as an MCP app; you still need to serve and host that app for clients to reach it.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
