How to Use MCP Tools
In this guide, we will explore how to connect your agents to one or more existing MCP servers. MCP (Model Context Protocol) enables your agents to dynamically discover and invoke tools using the MCP specification. This approach allows you to leverage already-running MCP servers in your infrastructure to provide domain-specific APIs and functionality to your agents.
Prerequisites
Before you begin, make sure you have completed the Getting Started with the Agents SDK tutorial and the How to Configure Agents guide. You should also be familiar with How to Create Agents that Use Tools.
You will also need to have at least one MCP server running. For more information about MCP, visit the Model Context Protocol website.
Step 1: Add MCP support to your project
Install the Agents SDK with MCP extras:
pip install zetaalpha.rag-agents[mcp]
Step 2: Register and Use MCPToolsProvider in Your Agent
Update your agent code to accept an MCPToolsProvider dependency and load tools from the configured MCP servers at runtime.
from typing import AsyncGenerator, List
from zav.agents_sdk import ChatAgentClassRegistry, ChatMessage, StreamableChatAgent
from zav.agents_sdk.adapters import MCPToolsProvider, ZAVChatCompletionClient
@ChatAgentClassRegistry.register()
class ChatAgent(StreamableChatAgent):
agent_name = "chat_agent"
def __init__(
self,
client: ZAVChatCompletionClient,
tools_provider: MCPToolsProvider
):
self.client = client
self.tools_provider = tools_provider
async def execute_streaming(
self,
conversation: List[ChatMessage]
) -> AsyncGenerator[ChatMessage, None]:
# Discover and register tools from MCP servers
self.tools_registry.extend(await self.tools_provider.get_tools())
response = await self.client.complete(
bot_setup_description="You are a helpful assistant.",
messages=conversation,
stream=True,
tools=self.tools_registry,
execute_tools=True,
log_fn=self.debug,
)
async for chat_client_response in response:
if chat_client_response.error is not None:
raise chat_client_response.error
if chat_client_response.chat_completion is None:
raise Exception("No response from chat completion client")
yield ChatMessage.from_orm(chat_client_response.chat_completion)
The MCPToolsProvider will connect to the MCP servers configured in agent_setups.json, discover all available tools, and add them to the agent's ToolsRegistry. The rest of the agent code is identical to other tool-using agents.
Step 3: Example – Filesystem MCP Server
Open your agent_setups.json file and add the following configuration. This setup will launch the official filesystem MCP server and allow your agent to perform filesystem operations on the specified paths.
[
{
"agent_identifier": "chat_agent",
"agent_name": "chat_agent",
"llm_client_configuration": {
"vendor": "openai",
"vendor_configuration": {},
"model_configuration": {
"name": "gpt-4o-mini",
"type": "chat",
"temperature": 0.0
}
},
"agent_configuration": {
"mcp_configuration": {
"servers": [
{
"transport": "stdio",
"transport_config": {
"stdio": {
"name": "filesystem",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/<YOUR_USER>/Desktop",
"/Users/<YOUR_USER>/Downloads"
]
}
}
}
]
}
}
}
]
More information and configuration options for the filesystem MCP server can be found in the filesystem MCP server repository.
Step 4: (Optional) OAuth Client Registration
If your MCP server requires dynamic OAuth client registration, you can provide an oauth_client block under each transport in transport_config (except for stdio). The SDK uses the RFC 7591 metadata schema to register the client at runtime.
{
"server_url": "https://mcp.example.com/register",
"client_metadata": {
"redirect_uris": ["https://app.example.com/callback"],
"token_endpoint_auth_method": "client_secret_post",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "read write",
"client_name": "My MCP Client",
"client_uri": "https://app.example.com",
"logo_uri": "https://app.example.com/logo.png",
"contacts": ["team@app.example.com"],
"tos_uri": "https://app.example.com/terms",
"policy_uri": "https://app.example.com/policy",
"jwks_uri": "https://app.example.com/jwks.json",
"jwks": { /* your JWKS object */ },
"software_id": "com.example.myclient",
"software_version": "1.0.0"
}
}
Example configuration in your agent_setups.json (note that oauth_client must be nested inside the chosen transport block):
[
{
"agent_identifier": "chat_agent",
"agent_name": "chat_agent",
/* ... */
"agent_configuration": {
"mcp_configuration": {
"servers": [
{
"transport": "http-sse",
"transport_config": {
"sse": {
/* ... */
"oauth_client": {
"server_url": "https://mcp.example.com/register",
"client_metadata": {
"redirect_uris": ["https://app.example.com/callback"],
"token_endpoint_auth_method": "client_secret_post",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "read write",
"client_name": "My MCP Client"
}
}
}
}
}
]
}
}
}
]
Schema of mcp_configuration
Below is the JSON schema for the mcp_configuration block in agent_setups.json.
{
"client_session_timeout_seconds": number,
"convert_schemas_to_strict": boolean,
"servers": [
{
"transport": "stdio" | "http-sse" | "streamable-http",
"transport_config": {
"stdio": {
"name": string,
"command": string,
"args": [string, ...],
"env": { string: string, ... },
"cwd": string,
"encoding": string,
"encoding_error_handler": "strict" | "replace" | "ignore"
},
"sse": {
"name": string,
"url": string,
"headers": { string: string, ... },
"timeout": number,
"sse_read_timeout": number,
"oauth_client": {
"server_url": string,
"client_metadata": {/* see Step 4 metadata schema */}
}
},
"streamable_http": {
"name": string,
"url": string,
"headers": { string: string, ... },
"timeout": number,
"sse_read_timeout": number,
"terminate_on_close": boolean,
"oauth_client": {
"server_url": string,
"client_metadata": {/* see Step 4 metadata schema */}
}
}
}
}
]
}
Fields
- client_session_timeout_seconds: The timeout in seconds for initializing the MCP client session and making RPC calls.
- convert_schemas_to_strict: If
true, convert MCP input schemas to strict JSON Schema (no additional properties allowed). - servers: A list of MCP server configurations. Each entry describes how to connect to one MCP server.
- transport (
"stdio","http-sse", or"streamable-http"): The transport mechanism to use. - transport_config: Transport-specific settings.
- stdio: Configuration for StdIO transport.
- name: Logical identifier for this MCP server instance.
- command: Shell command to launch the MCP server process.
- args: List of arguments passed to the command.
- env: (Optional) Environment variables for the process.
- cwd: (Optional) Working directory for the process.
- encoding: (Optional) Character encoding for communication.
- encoding_error_handler: (Optional) Error handler for encoding issues.
- sse: Configuration for HTTP/SSE transport.
- name: Logical identifier for this MCP server instance.
- url: The URL of the MCP SSE endpoint.
- headers: (Optional) HTTP headers to include in the SSE connection.
- timeout: (Optional) HTTP request timeout in seconds.
- sse_read_timeout: (Optional) Timeout for reading SSE events in seconds.
- oauth_client: (Optional) OAuth dynamic client registration settings (see Step 4).
- streamable_http: Configuration for Streamable HTTP transport.
- name: Logical identifier for this MCP server instance.
- url: The URL of the MCP server endpoint.
- headers: (Optional) HTTP headers to include in the connection.
- timeout: (Optional) HTTP request timeout in seconds.
- sse_read_timeout: (Optional) Timeout for reading SSE events in seconds.
- terminate_on_close: (Optional) Whether to terminate the connection when the client closes.
- oauth_client: (Optional) OAuth dynamic client registration settings (see Step 4).
- stdio: Configuration for StdIO transport.
- transport (
For more details on MCP, visit the Model Context Protocol website.