Model Context Protocol

Consider an ops agent connecting to an analytics MCP server: the trace shows the handshake, the protocol version, the server’s identity and the 5 tools it offers. Asked “Which agent had the worst p95 turn latency in the last 7 days?”, it lists the metrics, computes one per agent in a single step, answers, and the hallucination check finds every figure in the returned rows.

The same server could be added, unchanged, to an IDE assistant or the MCP Inspector. One server, any client.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: server/discover (or legacy initialize)
    S-->>C: protocol versions · capabilities · identity
    C->>S: tools/list
    S-->>C: names · descriptions · schemas
    C->>S: tools/call {name, arguments}
    S-->>C: content (+ structuredContent) or isError
    S--)C: notifications: progress, list changes

1. Discover: the client learns the server’s protocol versions, capabilities and identity. Older revisions used an initialize / initialized handshake; the 2026-07-28 revision replaces it with server/discover and makes the protocol stateless: every request carries its protocol version and client capabilities in _meta.
2. List: tools/list returns each tool’s name, description and schemas.
3. Call: tools/call with arguments; the result is content (and structuredContent when the tool declares an outputSchema), or isError with a message the model can read.

A robust client uses server/discover for newer servers and falls back to initialize for legacy ones, and records which one each connection used.

Where MCP is used: the pattern is always “let an AI app reach a system without bespoke glue”:

The server is small on purpose (MCP Python SDK):

server = MCPServer(name=..., version=..., instructions=...)

@server.tool(annotations=READ_ONLY)
async def run_query(sql: str, ctx: Context) -> QueryResult:
    """Run ONE read-only SELECT over the curated views (DuckDB SQL). Rows are capped."""
    return await _answer(ctx, source.query, sql)   # refusal → ToolError the model reads

@server.resource("source://manifest", mime_type="application/json")
def manifest() -> str: ...

build_server().run("stdio")

Type hints and docstrings become the tool schema; Pydantic return types become the outputSchema, so structured results come for free. Blocking database work runs off the event loop.

The client starts with configuration: which servers exist, how to reach them, and what their tools may do here:

mcp:
  servers:
    - name: analytics
      transport: stdio
      command: ["{python}", "-m", "agent_platform.knowledge.mcp.server.analytics"]
      namespace: analytics
      envelope: {surface: locked, side_effecting: false, required_permission: read_analytics}
      tools:
        run_query: {surface: locked, side_effecting: false, required_permission: query_analytics}
  default_envelope: {surface: human_controlled, side_effecting: true, reversible: false}

An unknown server gets the most restrictive envelope by default: human-controlled, side-effecting, irreversible.

A server’s tool, governed like ours:

graph TD
    L["tools/list · name, schemas"] --> TD["ToolDefinition · args model built from inputSchema"] --> G["Gatekeeper · envelope from OUR config"] --> E["Executor · deadline, idempotency"] --> A["Audit · facts, like any tool"]
    classDef c1 fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
    classDef c2 fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#1e3a8a
    classDef c3 fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#7c2d12
    classDef c4 fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px,color:#581c87
    classDef c5 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
    classDef c6 fill:#ccfbf1,stroke:#0f766e,stroke-width:2px,color:#134e4a
    class L c1
    class TD c2
    class G c3
    class E c4
    class A c5

Arguments are validated by a Pydantic model built from the server’s input schema, before the call leaves. The envelope (surface, reversibility, side effects, permission) comes from this deployment’s config, never from the server.

One task owns the session: the SDK client’s cancel scopes belong to the task that opened it, but tool calls arrive from whichever task runs the turn. So one task owns the client and callers hand it requests through a queue (the Active Object pattern). A call fails, never hangs, when the server has gone away. Every protocol event (handshake, listing, each call, notifications, close) is logged in full under the turn’s trace id.