Skip to content
Docs

Documentation navigation

MCP Integration

Registering MCP servers over stdio and HTTP, including auto-setup for third-party servers.

#MCP Integration

These examples wire external tool servers into an agent. MCP (Model Context Protocol) lets agents call tools that live in another process: local stdio servers, remote HTTP servers, or third-party servers installed on demand.

Register an MCP server and its tools become first-class tools on the agent: the agent picks when to call them, the SDK handles the MCP wire protocol from your application process.

#Stdio server (local)

Run a local Python MCP server over stdio:

Python 
import sys
from pathlib import Path
from maivn import Agent, MCPServer

stdio_mcp = MCPServer(
    name='local_stdio',
    transport='stdio',
    command=sys.executable,
    args=[str(Path('path/to/stdio_server.py'))],
)

agent = Agent(name='Stdio MCP Agent', system_prompt='...', api_key='...')
agent.register_mcp_servers([stdio_mcp])

The SDK spawns the server, runs MCP initialize/tools/list, and exposes each remote tool to the agent as local_stdio__<tool_name> (the server name is prepended to disambiguate when multiple servers are attached).

#HTTP server (remote)

The HTTP transport is identical from the SDK's perspective. Just point the server at a URL:

Python 
http_mcp = MCPServer(
    name='local_http',
    transport='http',
    url='http://127.0.0.1:8080/mcp',
)

agent.register_mcp_servers([http_mcp])

The agent calls local_http__<tool_name> exactly like a stdio server's tools. Configure headers and authentication on MCPServer; its compatibility rate-limit fields do not pace requests.

#Multiple servers on one agent

Mix transports freely:

Python 
from maivn.messages import HumanMessage

agent.register_mcp_servers([
    MCPServer(name='local_http', transport='http', url='http://127.0.0.1:8080/mcp'),
    MCPServer(name='local_stdio', transport='stdio', command=sys.executable, args=['server.py']),
])

agent.invoke([HumanMessage(content=(
    "Call local_http__echo_http with text='hello', then local_stdio__add_numbers "
    "with a=3 and b=5. Return the MCPProtocolSummary tool."
))])

#Third-party stdio servers via uvx

For installable third-party servers (e.g. mcp-server-fetch), the auto-setup helper drops them into an isolated environment without polluting your global Python:

Python 
from maivn import Agent, MCPAutoSetup, MCPServer

fetch_server = MCPServer(
    name='fetch',
    transport='stdio',
    auto_setup=MCPAutoSetup(
        provider='uvx',
        package='mcp-server-fetch',
    ),
    stdio_response_timeout_seconds=30,
)

agent = Agent(name='Fetch Agent', system_prompt='...', api_key='...')
agent.register_mcp_servers([fetch_server])

MCPAutoSetup ensures the package is available before the server starts. The current transport does not implement MCPSoftErrorHandling retries. Handle provider throttling in the server or application.

#Rate limits and quotas

max_calls_per_minute and max_calls_per_day are compatibility fields without an active limiter. Setting them does not protect an upstream quota. Apply required pacing and bounded retries in your server or application.

#Combining MCP with structured output

MCP tools work the same way as registered tools, including with final_tool and structured_output:

Python 
from pydantic import BaseModel, Field

class MCPProtocolSummary(BaseModel):
    """Capture MCP protocol results."""
    http_result: dict = Field(..., description='Result from HTTP MCP tool')
    stdio_result: dict = Field(..., description='Result from stdio MCP tool')
    notes: str = Field(default='Protocol demo complete.')

agent.toolify(name='mcp_protocol_summary', final_tool=True)(MCPProtocolSummary)

agent.structured_output(model=MCPProtocolSummary).invoke(messages)

#Closing connections

When the agent is done, close the MCP connections so subprocesses and sockets shut down cleanly. Agent.close() is currently a no-op:

Python 
try:
    agent.invoke(messages)
finally:
    for server in agent.list_mcp_servers():
        server.close()
    agent.client.close()

In long-running services, attach this to the process lifecycle (e.g. FastAPI's shutdown hook).

#What's next

  • Connecting MCP Servers — the concept guide: where MCP tools run, choosing a transport, authentication, and failure handling.
  • Agents & Tools — combining MCP tools with registered tools, hooks, and cross-agent dependencies.
  • Real-World Projects — the financial-planner project uses MCP servers for live market data.
  • MCP API reference: docs/api/mcp.md.