Model Context Protocol (MCP) | LiveKit Documentation

ONLY Available in

Python

Overview

LiveKit Agents has first-class support for Model Context Protocol (MCP) servers.

To use MCP, install the optional dependencies:

uv add livekit-agents[mcp]~=1.4

Then pass the MCP server URL to the AgentSession or Agent constructor. The tools will be automatically loaded like any other tool.

from livekit.agents import mcp

session = AgentSession(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerHTTP("https://your-mcp-server.com")
    ]
)

from livekit.agents import mcp

agent = Agent(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerHTTP("https://your-mcp-server.com")
    ]
)

HTTP servers

Use MCPServerHTTP to connect to a remote MCP server over HTTP:

from livekit.agents import AgentSession, mcp

session = AgentSession(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerHTTP("https://your-mcp-server.com/sse")
    ]
)

Tip

The transport type is auto-detected from the URL path. URLs ending in /sse use Server-Sent Events transport, and URLs ending in /mcp use streamable HTTP transport. Override this with the transport_type parameter if needed.

Local servers (stdio)

Use MCPServerStdio to launch a local MCP server process and communicate over stdin/stdout. This is useful for MCP servers distributed as CLI tools:

from livekit.agents import AgentSession, mcp

session = AgentSession(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerStdio(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
        )
    ]
)

The env and cwd parameters let you customize the child process environment and working directory.

Authentication

Pass authentication headers to an MCP server with the headers parameter:

import os
from livekit.agents import AgentSession, mcp

session = AgentSession(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerHTTP(
            "https://actions.zapier.com/mcp/sse",
            headers={
                "Authorization": f"Bearer {os.environ['ZAPIER_API_KEY']}"
            },
        )
    ]
)

Filtering tools

Limit which tools from an MCP server are exposed to the LLM with the allowed_tools parameter. Tools not in the list are filtered out:

from livekit.agents import mcp

mcp_server = mcp.MCPServerHTTP(
    "https://your-mcp-server.com/sse",
    allowed_tools=["search_products", "get_product_details"],
)

Multiple servers

The mcp_servers parameter accepts a list. You can combine different server types, and all servers are initialized in parallel:

from livekit.agents import AgentSession, mcp

session = AgentSession(
    # ... other arguments ...
    mcp_servers=[
        mcp.MCPServerHTTP("https://api.example.com/mcp"),
        mcp.MCPServerStdio(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/data"],
        ),
    ]
)

If an individual server fails to connect, the error is logged but does not prevent the agent from starting.

Combining MCP tools with function tools

MCP tools are automatically combined with any function tools defined on your Agent or AgentSession. The LLM sees all tools together and can call any of them:

from livekit.agents import Agent, function_tool, RunContext, mcp

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful assistant with access to a knowledge base and local tools.",
            mcp_servers=[
                mcp.MCPServerHTTP("https://your-mcp-server.com/sse")
            ],
        )

    @function_tool()
    async def save_note(self, context: RunContext, text: str) -> str:
        """Save a note for the user.

        Args:
            text: The note content to save.
        """
        # your custom logic here
        return "Note saved successfully."

In this example, the LLM can call both the MCP server's tools and the save_note function tool.

Agent vs AgentSession placement

You can set mcp_servers on either AgentSession or Agent. If the Agent specifies mcp_servers, those servers replace (not merge with) any servers set on the AgentSession. If the Agent does not set mcp_servers, the session's servers are used as a fallback.

Tip

Set mcp_servers on the AgentSession for shared defaults across multiple agents in a workflow. Set mcp_servers on a specific Agent only when that agent needs a different set of MCP servers. This is the same override pattern used by stt, llm, tts, and other agent properties.

MCP Agent

A voice AI agent with an integrated Model Context Protocol (MCP) client for the LiveKit API.

Shopify voice shopper

Advanced example combining MCP with function tools and dynamic agent switching.