mcp_service

MCP (Model Context Protocol) client for integrating external tools with LLMs.

class pipecat.services.mcp_service.MCPClient(server_params: StdioServerParameters | SseServerParameters | StreamableHttpParameters, tools_filter: list[str] | None = None, tools_output_filters: dict[str, Callable[[Any], Any]] | None = None, **kwargs)

Bases: BaseObject

Client for Model Context Protocol (MCP) servers.

Enables integration with MCP servers to provide external tools and resources to LLMs. Supports stdio, SSE, and streamable HTTP server connections with automatic tool registration and schema conversion.

The client maintains a persistent connection to the MCP server. It must be used as an async context manager or explicitly started and closed:

async with MCPClient(server_params=...) as mcp:
    tools = await mcp.register_tools(llm)

Raises:

TypeError – If server_params is not a supported parameter type.

__init__(server_params: StdioServerParameters | SseServerParameters | StreamableHttpParameters, tools_filter: list[str] | None = None, tools_output_filters: dict[str, Callable[[Any], Any]] | None = None, **kwargs)

Initialize the MCP client with server parameters.

Parameters:

• server_params – Server connection parameters (stdio, SSE, or streamable HTTP).

• tools_filter – Optional list of tool names to register. If None, all tools are registered.

• tools_output_filters – Optional dict mapping tool names to filter functions that process tool outputs. Each filter function receives the raw tool output (any type) and returns the processed output (any type).

• **kwargs – Additional arguments passed to the parent BaseObject.

async start() → None

Start a persistent connection to the MCP server.

Opens the transport and initializes the MCP session. The session is reused for all subsequent tool calls and schema requests until close() is called.

Can also be used via async context manager:

async with MCPClient(server_params=...) as mcp:
    ...

async close() → None

Close the persistent MCP connection.

Safe to call multiple times or without having called start().

async register_tools(llm: LLMService | LLMSwitcher) → ToolsSchema

Register all available MCP tools with an LLM service.

Discovers available tools from the active session, converts their schemas to Pipecat format, and registers them with the LLM service.

This is the equivalent of calling get_tools_schema() followed by register_tools_schema().

Parameters:

llm – The Pipecat LLM service to register tools with.

Returns:

A ToolsSchema containing all successfully registered tools.

async get_tools_schema() → ToolsSchema

Get the schema of all available MCP tools without registering them.

Requires the client to be started via start() or async with.

Returns:

A ToolsSchema containing all available tools. This can be used for subsequent registration using register_tools_schema().

async register_tools_schema(tools_schema: ToolsSchema, llm: LLMService | LLMSwitcher) → None

Register the MCP tools (previously obtained from get_tools_schema()) with the LLM service.

Parameters:

• tools_schema – The ToolsSchema to register with the LLM service.

• llm – The Pipecat LLM service to register tools with.