Skip to content

Envelope contract

Every MCP tool in the suite returns a uniform shape:

class Envelope[T]:
    status: Literal["ok", "error"]
    data: T | None
    warnings: list[str]
    metadata: dict[str, Any]  # tool_version, runtime_sec, etc.
    error: str | None

Why a uniform shape

Predictability matters more than minimalism here. An LLM agent calls forty different tools across three servers and needs a contract it can rely on for routing logic ("did the call succeed?", "what's the runtime?", "are there warnings I should propagate?"). The envelope gives it that without per-tool special cases.

Construction helpers

Structured response envelope for every MCP tool in the suite.

Every tool returns the same shape so agents (and humans) can rely on a predictable contract: status, data, warnings, and metadata. When a tool fails, status="error" and error is populated with a human-readable message; data is None.

Envelope

Bases: BaseModel, Generic[T]

Uniform tool response.

Tools should never raise to the MCP transport layer. They catch their own exceptions and convert to error() envelopes so the agent can reason about the failure.

Timer()

Tiny wall-clock timer for tool runtime metadata.

Source code in packages/rf-mcp-common/src/rf_mcp_common/envelope.py 
87
88
def __init__(self) -> None:
    self._start = time.perf_counter()

ok(data, *, warnings=None, metadata=None, tool_version=_DEFAULT_TOOL_VERSION, runtime_sec=None)

Build a successful envelope.

Source code in packages/rf-mcp-common/src/rf_mcp_common/envelope.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def ok(
    data: T,
    *,
    warnings: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
    tool_version: str = _DEFAULT_TOOL_VERSION,
    runtime_sec: float | None = None,
) -> Envelope[T]:
    """Build a successful envelope."""
    meta: dict[str, Any] = {"tool_version": tool_version}
    if runtime_sec is not None:
        meta["runtime_sec"] = round(runtime_sec, 4)
    if metadata:
        meta.update(metadata)
    return Envelope[T](
        status="ok",
        data=data,
        warnings=warnings or [],
        metadata=meta,
    )

error(message, *, warnings=None, metadata=None, tool_version=_DEFAULT_TOOL_VERSION)

Build a failure envelope with a human-readable message.

Returns Envelope[Any] rather than Envelope[None]: a failure carries data=None regardless of what the tool would have returned on success, so the envelope has to be assignable to every tool's declared Envelope[X] return type.

Source code in packages/rf-mcp-common/src/rf_mcp_common/envelope.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def error(
    message: str,
    *,
    warnings: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
    tool_version: str = _DEFAULT_TOOL_VERSION,
) -> Envelope[Any]:
    """Build a failure envelope with a human-readable message.

    Returns ``Envelope[Any]`` rather than ``Envelope[None]``: a failure
    carries ``data=None`` regardless of what the tool would have returned
    on success, so the envelope has to be assignable to every tool's
    declared ``Envelope[X]`` return type.
    """
    return Envelope[Any](
        status="error",
        data=None,
        warnings=warnings or [],
        metadata={"tool_version": tool_version, **(metadata or {})},
        error=message,
    )