LlamaIndex consumes MCP servers through the llama-index-tools-mcp package. You point a client at a server, convert its tools into LlamaIndex tools, and hand them to an agent. The wiring takes a few lines. The hard part is what comes after: choosing a transport, keeping the tool list small, and deciding what your agent does when a web tool fails.
This guide covers the wiring, the web-data decisions, and the LangChain and LangGraph equivalents, since many teams run both.
TL;DR
- Install
llama-index-tools-mcp, create aBasicMCPClient, wrap it inMcpToolSpec, and pass the resulting tools to an agent. BasicMCPClientaccepts SSE, streamable HTTP, or a local process, so the same agent code works against a hosted or local server.- For web data, the tool contract matters more than the connection: typed responses with explicit failure cases let an agent branch instead of improvise.
- LangChain and LangGraph use a different adapter (
langchain-mcp-adapters) but the same MCP server, so you write the web tooling once.
Table of Contents
- What MCP gives a LlamaIndex agent
- Connect LlamaIndex to an MCP server
- Why web tools need a stricter contract
- Which web primitives to expose
- The LangChain and LangGraph version
- Our perspective
- Try it with Gyrence
- FAQ
- Sources
What MCP gives a LlamaIndex agent
The Model Context Protocol is an open protocol for connecting LLM applications to external data sources and tools. Instead of hand-writing a function wrapper for every API, the agent asks an MCP server what tools exist and receives their names, descriptions, and input schemas.
LlamaIndex's own documentation describes two roles for MCP: connecting agents to external MCP servers for real-time information, and exposing LlamaIndex workflows as MCP servers to other applications. This article covers the first: your agent is the client, and a web data server is the tool provider.
Connect LlamaIndex to an MCP server
The LlamaIndex MCP guide shows the basic pattern. Install the package:
pip install llama-index-tools-mcp
Then build a client, convert the server's tools, and give them to an agent:
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
mcp_client = BasicMCPClient("YOUR_MCP_SERVER_URL")
tool_spec = McpToolSpec(client=mcp_client)
tools = await tool_spec.to_tool_list_async()
agent = FunctionAgent(
tools=tools,
llm=OpenAI(model="gpt-5-mini"),
system_prompt="You research the web. Report failures; do not guess.",
)
response = await agent.run("Summarize the pricing page at example.com")
Replace the model with whatever you run. The pattern is the point.
Pick a transport
Per the same documentation, BasicMCPClient supports SSE, streamable HTTP, and local processes, and you can also supply your own ClientSession when you need control over the connection. A practical rule:
| Transport | Use it when | Trade-off |
|---|---|---|
| Local process (stdio) | Prototyping, a server you run on your own machine | You own process lifecycle and secrets on disk |
| Streamable HTTP | Production agents calling a hosted server | Network latency; you need auth and timeouts |
| SSE | A server that only exposes an SSE endpoint | Older pattern; check what your server supports |
We walk through running the examples first and choosing afterward in Run MCP Client Examples First, Then Choose a Transport. If you want the client built step by step, see 5 Steps to Ship an MCP Client.
Why web tools need a stricter contract
A calculator tool either returns a number or raises. A web tool has many more ways to go wrong: the page is blocked, the content is behind a login, JavaScript never rendered, the response is a PDF, or the page loaded but the field you wanted is not there.
Most scraping tools collapse these into one of two outcomes: text, or an exception string. An LLM reading "Error: failed" will often retry blindly, or worse, summarize whatever partial text it received. That is how a confident wrong answer ends up in your RAG index.
The fix is a contract where every outcome is a named case. Gyrence returns a typed, discriminated-union response from each call, failures included, so the agent can read a status-style discriminator and branch: retry, try another source, or report that the data is unavailable. Our post on LlamaIndex web scraping covers decoupling fetching from failure handling in detail.
What to check in any web tool you plug into MCP:
- Does a failure have a type? Blocked, not found, timeout, and empty extraction should be distinguishable.
- Can you cap cost? An agent in a loop can call a tool hundreds of times. You want a hard spending cap, not a surprise invoice.
- Is the output model-ready? Clean markdown for reading, schema-validated JSON for facts.
- Is provenance kept? Compliance and research workflows need the source URL attached to every value.
Which web primitives to expose
More tools in the context window means more wrong tool choices. Expose the smallest set that covers the job. Gyrence has five primitives, and most agents need only two or three:
- Search: find candidate URLs when the agent has no starting point. See Web Search Tool for Autonomous Agents.
- Fetch: render a page, strip boilerplate, return markdown.
- Extract: pull structured JSON using a prompt or schema. Details in Structured JSON Extraction From Web.
- Traverse: walk a site outward from a starting URL.
- Map: list a domain's URL graph before deciding what to fetch.
For a RAG ingestion agent, Map plus Fetch is often enough. For a monitoring or lead-enrichment agent, Search plus Extract usually is. The idea of small tools that combine is explained in Composable Agent Tools.
One structural note: structured outputs make retrieval more deterministic. Our guide to structured web data for RAG argues that schema-compliant content reduces hallucination risk because fact extraction stops being probabilistic. If you are also thinking about how your own pages expose structured data to LLMs, a structured data audit for AI search is a quick way to see the other side of the problem.
The LangChain and LangGraph version
The same MCP server works in LangChain. The langchain-mcp-adapters package converts MCP tools into LangChain tools usable by LangGraph agents, and its MultiServerMCPClient connects to several servers at once:
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
client = MultiServerMCPClient({
"web": {"url": "YOUR_MCP_SERVER_URL", "transport": "http"},
})
tools = await client.get_tools()
agent = create_agent("openai:gpt-4.1", tools)
For LangGraph web scraping, this means a graph node can call the same Fetch and Extract tools as a LlamaIndex agent. Keep the failure handling in the graph: route on the discriminator, with one edge for success, one for retryable failures, and one for "report and stop". You do not need separate scraping code per framework.
Our perspective
We built Gyrence on one belief: web data is a storm, and the job of an API is to tell you honestly what weather you got. Most of the damage we see in agent pipelines is not a connection bug. It is silent partial success: a page that half-rendered, an extraction that returned nulls, a block page summarized as if it were the article.
MCP makes tool access easy, which raises the stakes. When an LLM decides which tool to call and how to read the result, a vague response is a decision made on bad information. So we return typed results for every outcome, bundle LLM extraction with no separate AI charge, and let you set spending caps so a runaway loop hits a ceiling instead of your card.
Our advice: test failure paths before happy paths. Point your agent at a blocked page, a 404, and a PDF, and read what it does. If it improvises, fix the contract, not the prompt.
— Glen
Try it with Gyrence
Gyrence exposes a hosted MCP endpoint, so you can skip running a server. The connect guide shows how to attach an agent, and Set Up an MCP Server in 5 Minutes covers the typed-data setup. Plans on the pricing page include a Free tier, Pay-As-You-Go, and monthly tiers: Standard at $75 per month, Growth at $299 per month, and Scale at $549 per month. If you need change alerts on pages your agent depends on, see WebDoppler.
FAQ
Does LlamaIndex support MCP natively?
Yes, through the llama-index-tools-mcp package. It connects to MCP servers and returns a tool list you can pass to any LlamaIndex agent, as the official docs describe.
Can I use the same MCP server with LangChain and LlamaIndex?
Yes. MCP is a protocol, so the server does not care which client connects. LlamaIndex uses BasicMCPClient and McpToolSpec; LangChain uses langchain-mcp-adapters. Your tool logic and failure handling stay on the server side.
How do I stop an agent from running up a scraping bill?
Set limits at two layers. In the agent, cap iterations and tool calls per run. At the provider, use a hard spending cap on the workspace. Do both, because an agent bug and a billing surprise are different failures.
Which transport should I use in production?
Streamable HTTP for a hosted server, with explicit timeouts and authentication. Use a local process for development, where you control the lifecycle of the server.
Sources
- Using MCP Tools with LlamaIndex
- Using LlamaIndex with AI Agents
- langchain-mcp-adapters reference
- Model Context Protocol specification text