MCP Servers

​

What is MCP?

​

Basic Usage

from timbal import Agent
from timbal.core import MCPServer

agent = Agent(
    name="my_agent",
    model="openai/gpt-4o-mini",
    tools=[
        # stdio: spawn a local server process
        MCPServer(
            name="filesystem",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "."],
        ),
        # http: connect to a remote server (streamable HTTP)
        MCPServer(
            name="timbal",
            transport="http",
            url="https://api.timbal.ai/mcp",
        ),
    ],
)

​

The project API

project_tools = MCPServer(name="app", transport="http", service="api")

​

Configuration

​

Authentication

import os

timbal_mcp = MCPServer(
    name="timbal",
    transport="http",
    url="https://api.timbal.ai/mcp",
    headers={"Authorization": f"Bearer {os.environ['TIMBAL_API_KEY']}"},
)

github_mcp = MCPServer(
    name="github",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
    env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
)

​

How Results Are Handled

• Text content becomes a plain string (or a list of strings for multiple blocks)
• Images, audio, and binary resources become Timbal Files, forwarded to the model as file content — vision models can see returned images directly
• Structured content is returned as-is when the server sends no text representation
• Errors (isError) raise inside the tool call, so the model receives a proper error tool result and can self-correct

​

Approval from Annotations

MCPServer(
    name="timbal",
    transport="http",
    url="https://api.timbal.ai/mcp",
    approval="destructive",  # or "all", or lambda tool: tool.name in {"delete_project"}
)

• "destructive" gates tools whose annotations mark them destructive (destructiveHint not false and readOnlyHint not true). Tools with no annotations at all are not gated — gating them would mean gating every tool of every server that never annotated. Note the spec default: a tool that sets any annotation without destructiveHint: false counts as destructive, so a server that annotates readOnlyHint: false on every writer gates every writer.
• "all" gates every tool.
• A one-argument callable receives the server’s mcp.types.Tool once, at resolve time, and returns True to gate every call of that tool.
• A two-argument callable receives the tool and the call’s arguments and is evaluated per call, so one tool that multiplexes subcommands can gate some and wave others through. It may be async and may return a bool, a dict, or an ApprovalPolicyDecision (the same contract as requires_approval):

def needs_approval(tool, arguments):
    if tool.name == "codegen":
        return arguments.get("command") in {"delete-workforce"}
    return tool.name in {"delete_kb_file"} or (tool.annotations and tool.annotations.destructiveHint is True)

MCPServer(name="timbal", transport="http", url="https://api.timbal.ai/mcp", approval=needs_approval)

​

Elicitation

async for event in agent(prompt="Swap the KB to 1586"):
    if isinstance(event, InteractionEvent) and event.kind == "mcp_elicitation":
        print(event.payload["message"])            # the server's question
        print(event.payload["requested_schema"])   # flat JSON schema of primitives
        interaction_id = event.interaction_id

# Render the form, then resume with the answer:
result = await agent(
    prompt="Swap the KB to 1586",
    parent_id=paused_run_id,
    resume={interaction_id: {"confirm": True}},
).collect()

​

Server Notifications

• tools/list_changed marks the cached tool list stale. It is refetched at the next run, never mid-run — swapping tools under the model’s feet would also invalidate the prompt cache.
• Log messages (notifications/message) are forwarded to structlog as "MCP server log" with server, level, logger, and data.
• Sampling (sampling/createMessage) is served with sampling_model= when set. The call runs as an mcp_sampling LLM span under the in-flight tool call, so its usage shows up in the trace.

​

Connection Lifecycle

server = MCPServer(transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])
agent = Agent(name="my_agent", model="openai/gpt-4o-mini", tools=[server])

result = await agent(prompt="List the files in the current directory").collect()

await server.close()

• Transport dies mid-call (server process exits, HTTP connection refused): the in-flight call fails immediately with connection lost during tools/call ... instead of hanging, the connection is forgotten, and the next call reconnects. The cached tools stay valid.
• Stale session (an HTTP server restarted or expired the session while you were idle, so it 404s your Mcp-Session-Id with Session terminated): the session is reset and the request retried once, transparently. Safe for any request — a 404 means the server never saw it.
• Server unreachable: ConnectionError("MCP server 'name' failed to connect: ConnectError: ...") with the real cause, not anyio’s unhandled errors in a TaskGroup.
• Server accepts but never answers: timeout= (default 600s, per tool via tool_timeouts=) turns it into a TimeoutError; the session stays up and the next call works. The handshake is bounded only by connect_timeout= (default None, but the TCP connect itself is capped at 30s).
• Slow HTTP tools: the transport’s read timeout is unbounded, so a tools/call that takes minutes completes. (A bare httpx.AsyncClient applied its 5-second default to the SSE read and the SDK swallowed the resulting ReadTimeout, so any HTTP tool slower than 5s hung the call forever.) Connect stays bounded at 30s (or connect_timeout) even when connect_timeout=None.

​

Dynamic Resolution

​

Codegen CLI

# stdio server
python -m timbal.codegen add-mcp --name fs \
  --command npx --args '["-y", "@modelcontextprotocol/server-filesystem", "."]'

# http server — $VARS are emitted as os.environ lookups, never hardcoded
python -m timbal.codegen add-mcp --name timbal \
  --url https://api.timbal.ai/mcp \
  --headers '{"Authorization": "Bearer $TIMBAL_API_KEY"}'

# import a standard mcpServers JSON config (claude-desktop / cursor style)
python -m timbal.codegen add-mcp --from-json @mcp.json