Skip to main content

Using MCP in Custom Agents

note

This guide covers using MCP tools in a custom agent class. If you're using the built-in agent, configure MCP servers via the CLI instead — see Using MCP Tools.

Prerequisites​

Step 1: Install the MCP Extra​

pip install zetaalpha.agents[mcp]

Step 2: Accept MCPToolsProvider as a Dependency​

Update your agent class to accept an MCPToolsProvider and load tools 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]:
        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 connects to all MCP servers configured in agent_setups.json, discovers available tools, and returns them as SDK Tool objects.

Step 3: Configure MCP Servers​

Add server configuration to your agent_setups.json:

[
  {
    "agent_identifier": "chat_agent",
    "agent_name": "chat_agent",
    "llm_client_configuration": { "..." : "..." },
    "agent_configuration": {
      "mcp_tools_provider_configuration": {
        "servers": [
          {
            "transport": "stdio",
            "transport_config": {
              "stdio": {
                "name": "filesystem",
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
              }
            }
          }
        ]
      }
    }
  }
]

See Using MCP Tools for transport options, OAuth configuration, and the full schema.