MCP Integration Guide

A step-by-step guide for integrating MCP (Model Context Protocol) servers with Elsai agents.

What you need

• elsai-agents installed
• uvx (from uv) or the MCP server package installed
• The MCP server package you want to use

Step 1: Install uvx

uvx lets you run MCP servers without installing them:

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Find an MCP server

Browse the MCP server registry or use popular ones:

# Test a server works
uvx mcp-server-fetch --help

Step 3: Connect and use

from elsai import Agent
from elsai.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-fetch"],
    ))
)

with client:
    agent = Agent(tools=client.list_tools_sync())
    result = agent("Fetch the homepage of https://example.com and summarise it")
    print(result)

Common MCP servers

Filesystem

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-filesystem", "/path/to/allowed/dir"],
    ))
)

SQLite database

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-sqlite", "--db-path", "myapp.db"],
    ))
)

GitHub

import os

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-github"],
        env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
    ))
)

Web search (Brave)

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-brave-search"],
        env={"BRAVE_API_KEY": os.environ["BRAVE_API_KEY"]},
    ))
)

PostgreSQL

client = MCPClient(
    lambda: stdio_client(StdioServerParameters(
        command="uvx",
        args=["mcp-server-postgres", os.environ["DATABASE_URL"]],
    ))
)

Multiple servers

fs_client = MCPClient(lambda: stdio_client(StdioServerParameters(command="uvx", args=["mcp-server-filesystem", "."])))
db_client = MCPClient(lambda: stdio_client(StdioServerParameters(command="uvx", args=["mcp-server-sqlite", "--db-path", "app.db"])))

with fs_client, db_client:
    tools = [
        *fs_client.list_tools_sync(),
        *db_client.list_tools_sync(),
    ]
    agent = Agent(tools=tools)
    agent("Read the config.json file and store the settings in the database")

HTTP/SSE transport

For MCP servers running as HTTP services:

from mcp.client.sse import sse_client

client = MCPClient(lambda: sse_client("http://localhost:8080/sse"))

with client:
    agent = Agent(tools=client.list_tools_sync())
    agent("Use the remote tools")

Filtering tools

Only expose specific tools from an MCP server:

with client:
    all_tools = client.list_tools_sync()

    # Only allow read operations
    safe_tools = [t for t in all_tools if t.name.startswith("read_")]
    agent = Agent(tools=safe_tools)

Production tips

1. Use async with for async code — always clean up the connection properly
2. Handle connection errors — wrap in try/except for production
3. Cache tool lists — calling list_tools_sync() has network overhead; cache it
4. Scope filesystem access — only grant access to specific directories

import asyncio
from elsai import Agent
from elsai.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

async def main():
    client = MCPClient(
        lambda: stdio_client(StdioServerParameters(
            command="uvx",
            args=["mcp-server-filesystem", "./data"],
        ))
    )

    try:
        async with client:
            tools = await client.list_tools()
            agent = Agent(tools=tools)
            result = await agent.invoke_async("What files are in the data directory?")
            print(result)
    except Exception as e:
        print(f"MCP connection failed: {e}")

asyncio.run(main())