# How to Integrate MCP Servers with LiveKit Agents: A Complete Guide

> Integrate MCP servers with LiveKit Agents easily. Convert remote MCP tools into callable LLM functions by passing an MCPServer instance to AgentSession. Learn how now.

- Repository: [LiveKit/agents](https://github.com/livekit/agents)
- Tags: how-to-guide
- Published: 2026-03-06

---

**You can integrate MCP servers with LiveKit Agents by passing an `MCPServer` instance to the `mcp_servers` parameter of `AgentSession`, which automatically converts remote MCP tools into callable LLM functions.**

The **Model Context Protocol (MCP)** enables AI agents to discover and invoke tools exposed by external servers. In the `livekit/agents` repository, the framework provides first-class support for MCP integration, allowing voice agents to seamlessly call remote capabilities during conversations. This guide covers the architecture, implementation steps, and practical examples for connecting your LiveKit agents to MCP servers.

## Understanding the MCP Integration Architecture

The MCP integration in LiveKit Agents is built on a clean abstraction layer that handles transport, tool discovery, and execution.

### Core Classes in [`livekit/agents/llm/mcp.py`](https://github.com/livekit/agents/blob/main/livekit/agents/llm/mcp.py)

The primary implementation resides in [`livekit/agents/llm/mcp.py`](https://github.com/livekit/agents/blob/main/livekit/agents/llm/mcp.py), which defines three key components:

- **`MCPServer`** – The abstract base class that defines the interface for all MCP connections. It handles the lifecycle of the connection and provides methods for initialization and tool listing.
- **`MCPServerHTTP`** – A concrete implementation that communicates with remote MCP servers using HTTP transport. It automatically detects between **Server-Sent Events (SSE)** and **streamable-HTTP** based on the URL path, or you can force a specific transport via the `transport_type` parameter.
- **`MCPServerStdio`** – For local MCP servers, this class spawns the server as a subprocess and communicates over STDIO, useful for development or local tool chains.

### How `AgentSession` Handles MCP Servers

In [`livekit/agents/voice/agent_session.py`](https://github.com/livekit/agents/blob/main/livekit/agents/voice/agent_session.py), the `AgentSession` class accepts a list of `MCPServer` instances through the `mcp_servers` parameter. When `session.start()` is called, the framework:

1. **Initializes** each server by calling `MCPServer.initialize()`.
2. **Discovers tools** via `MCPServer.list_tools()` and converts them to LiveKit **function tools** using the `function_tool` utility from [`livekit/agents/llm/tool_context.py`](https://github.com/livekit/agents/blob/main/livekit/agents/llm/tool_context.py).
3. **Registers** these tools with the LLM context, making them available for invocation during the conversation.

Any errors returned by the MCP server are raised as `ToolError` exceptions within the agent framework.

## Installation and Setup

The MCP client library is not included in the base installation. You must install the optional `mcp` extra:

```bash

# Using pip

pip install "livekit-agents[mcp]"

# Or using uv from the repository root

uv sync --all-extras --dev

```

## Connecting to MCP Servers

LiveKit Agents supports two primary transport mechanisms for MCP integration.

### HTTP/SSE Transport with `MCPServerHTTP`

For remote MCP servers accessible via HTTP, use `MCPServerHTTP`. The class automatically detects the transport protocol based on the URL:

```python
from livekit.agents import mcp

# Auto-detect SSE vs streamable-HTTP

http_srv = mcp.MCPServerHTTP(url="https://my-mcp.example.com/mcp")

# Force specific transport

http_srv = mcp.MCPServerHTTP(
    url="https://my-mcp.example.com/mcp",
    transport_type="streamable_http"  # or "sse"

)

```

### Local Subprocess with `MCPServerStdio`

For local development or running MCP servers as binaries on the same machine:

```python

# Run a local MCP server binary

stdio_srv = mcp.MCPServerStdio(
    command="my-mcp-binary",
    args=["--port", "8000"]
)

```

### Filtering Available Tools

You can restrict which remote tools are exposed to the LLM using the `allowed_tools` parameter:

```python
http_srv = mcp.MCPServerHTTP(
    url="https://my-mcp.example.com/mcp",
    allowed_tools=["search", "weather", "calendar"]
)

```

## Complete Integration Example

Here is a complete implementation showing how to integrate an HTTP MCP server into a voice agent:

```python
import logging
from dotenv import load_dotenv
from livekit.agents import Agent, AgentServer, AgentSession, JobContext, cli, inference, mcp
from livekit.plugins import silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

logging.getLogger("mcp-agent").setLevel(logging.INFO)
load_dotenv()

class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=(
                "You can retrieve data via the MCP server. "
                "Answer user questions using the remote tools."
            ),
        )

    async def on_enter(self):
        self.session.generate_reply(
            instructions="Hi! Ask me anything.", 
            allow_interruptions=True
        )

# Create the MCP server connection

mcp_srv = mcp.MCPServerHTTP(url="http://localhost:8000/mcp")

# Assemble the voice session with MCP integration

session = AgentSession(
    vad=silero.VAD.load(),
    stt=inference.STT("deepgram/nova-3", language="multi"),
    llm=inference.LLM("openai/gpt-4.1-mini"),
    tts=inference.TTS("cartesia/sonic-3"),
    turn_detection=MultilingualModel(),
    mcp_servers=[mcp_srv],  # Integrate MCP here

)

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    await session.start(agent=MyAgent(), room=ctx.room)

if __name__ == "__main__":
    cli.run_app(server)

```

*Source:* [`examples/voice_agents/mcp/mcp-agent.py`](https://github.com/livekit/agents/blob/main/examples/voice_agents/mcp/mcp-agent.py) in the [livekit/agents](https://github.com/livekit/agents) repository.

## Real-World Use Case: Zapier Integration

For production deployments, you might want to configure MCP servers dynamically via environment variables. This example shows integration with Zapier's MCP server:

```python
import os
import logging
from dotenv import load_dotenv
from livekit.agents import Agent, AgentServer, AgentSession, JobContext, cli, inference, mcp, metrics
from livekit.plugins import silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

load_dotenv(dotenv_path=".env.local")
logger = logging.getLogger("voice-agent")

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=(
                "You are a voice assistant that can trigger Zapier automations via MCP. "
                "Keep answers short and clear."
            ),
            stt=inference.STT("deepgram/nova-3"),
            llm=inference.LLM("google/gemini-2.5-flash"),
            tts=inference.TTS("rime/arcana"),
            turn_detection=MultilingualModel(),
        )

    async def on_enter(self):
        self.session.generate_reply(
            instructions="Hey, how can I help you today?", 
            allow_interruptions=True
        )

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx: JobContext):
    # Dynamic configuration via environment variable

    zapier_url = os.getenv("ZAPIER_MCP_SERVER")
    mcp_servers = [mcp.MCPServerHTTP(url=zapier_url)] if zapier_url else []
    
    session = AgentSession(
        vad=silero.VAD.load(),
        mcp_servers=mcp_servers,
    )
    await session.start(agent=Assistant(), room=ctx.room)

if __name__ == "__main__":
    cli.run_app(server)

```

*Source:* [`examples/voice_agents/zapier_mcp_integration.py`](https://github.com/livekit/agents/blob/main/examples/voice_agents/zapier_mcp_integration.py) in the [livekit/agents](https://github.com/livekit/agents) repository.

## Summary

To successfully integrate MCP servers with LiveKit Agents, remember these key points:

- **Install the MCP extra**: Use `pip install "livekit-agents[mcp]"` to get the required client libraries.
- **Choose your transport**: Use `MCPServerHTTP` for remote HTTP/SSE endpoints or `MCPServerStdio` for local subprocesses.
- **Pass to AgentSession**: Supply your server instances via the `mcp_servers` parameter when constructing `AgentSession`.
- **Tool filtering**: Use `allowed_tools` to restrict which remote capabilities your agent can access.
- **Automatic conversion**: The framework handles initialization, tool discovery, and conversion to LiveKit function tools automatically.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) in LiveKit Agents?

The **Model Context Protocol (MCP)** is an open standard that allows AI agents to connect to external data sources and tools. In LiveKit Agents, MCP integration enables voice agents to discover and invoke remote tools exposed by MCP servers as if they were native functions, handled through the `MCPServer` abstraction in [`livekit/agents/llm/mcp.py`](https://github.com/livekit/agents/blob/main/livekit/agents/llm/mcp.py).

### How do I choose between MCPServerHTTP and MCPServerStdio?

Use **`MCPServerHTTP`** when connecting to remote MCP servers accessible via HTTP endpoints, supporting both Server-Sent Events (SSE) and streamable-HTTP transports. Use **`MCPServerStdio`** when running a local MCP server binary on the same machine, where the framework spawns the process and communicates over standard input/output. The HTTP variant is preferred for production deployments, while STDIO suits local development.

### Can I restrict which tools from an MCP server are available to the agent?

Yes. When constructing an `MCPServerHTTP` instance, pass the `allowed_tools` parameter with a list of tool names to expose. For example: `MCPServerHTTP(url="https://api.example.com/mcp", allowed_tools=["search", "weather"])`. Only the specified tools will be converted to LiveKit function tools and registered with the LLM, providing security and reducing token usage.

### What happens if the MCP server returns an error during tool execution?

If an MCP server returns an error during tool invocation, the LiveKit Agents framework raises a **`ToolError`** exception. This error propagates through the agent's execution context, allowing you to handle failures gracefully within your agent logic or let the framework manage the error response to the LLM, maintaining robust conversation flow even when external tools fail.