MCP servers

The Model Context Protocol is an open standard for exposing tools to AI agents. If a capability already exists as an MCP server — filesystem access, a database, an internal service — you can attach it to a realtime agent directly instead of hand-writing client tools.

Attaching servers (Python)

Install the extra — pip install 'cosmo-ai-sdk[mcp]' — then pass a config file or inline server definitions:

from pathlib import Path
from cosmo_ai import CosmoRealtime

client = CosmoRealtime(api_key=os.environ["COSMO_API_KEY"])
agent = client.agent(
    instructions="You can use the connected MCP tools to help the user.",
    mcp=Path("./mcp.json"),        # standard .mcp.json format
)

{
  "mcpServers": {
    "files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

Or define servers in code with McpStdioServer:

from cosmo_ai.mcp import McpStdioServer

files = McpStdioServer(
    name="files",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "./data"],
)
agent = client.agent(instructions="…", mcp=[files])

At agent.start() the SDK launches each server, lists its tools, and registers them for the session. Servers stay alive for the whole session — including across reconnects — and are shut down at session end.

Swift follows the same shape; see the MCPExample target in the Swift package for a complete program that loads .mcp.json and proxies calls.

Tool namespacing

MCP tools join the session's tool surface under mcp__<server>__<tool> — a filesystem server named files contributes mcp__files__read_file, and that's the name you'll see in tool-call events and hook matchers:

@hooks.pre_tool_use(matcher="mcp__files__write_*")
def read_only(ctx):
    return PreToolUseResult(permission="deny", reason="filesystem is read-only in calls")

The namespacing prevents collisions between servers and makes provenance obvious in logs and tool timelines.

Errors

Misconfiguration fails fast: a malformed config file raises McpConfigError when the agent starts, and using mcp= without the extra installed raises McpExtraNotInstalled. A server that dies mid-session fails its tools' calls (surfaced to the model as tool errors) without ending the session.