MCP Minimal

Source: examples/tools/mcp_minimal.py

Introduction

MCP and JSON-RPC define interoperable tool transport contracts, and Toolformer motivates why model behavior improves when tool calls are explicit and machine-checked. This example provides the minimal MCP server/toolbox path for validating protocol-level integration inside the framework runtime.

Technical Implementation

  1. Configure Tracer with JSONL + console output so each run emits machine-readable traces and lifecycle logs.

  2. Build the runtime surface (public APIs only) and execute Toolbox.invoke(...) with a fixed request_id.

  3. Configure and invoke Toolbox integrations (core/script/MCP/callable) before assembling the final payload.

  4. Print a compact JSON payload including trace_info for deterministic tests and docs examples.

        flowchart LR
    A["Input prompt or scenario"] --> B["main(): runtime wiring"]
    B --> C["Toolbox.invoke(...)"]
    C --> D["MCP server registration exposes namespaced tool contracts"]
    C --> E["Tracer JSONL + console events"]
    D --> F["ExecutionResult/payload"]
    E --> F
    F --> G["Printed JSON output"]
    
 1from __future__ import annotations
 2
 3import json
 4import sys
 5from pathlib import Path
 6
 7from design_research_agents import MCPServerConfig, Toolbox, ToolResult, Tracer
 8
 9
10def _run_report() -> dict[str, object]:
11    with Toolbox(
12        mcp_servers=(
13            MCPServerConfig(
14                id="local_core",
15                command=(sys.executable, "-m", "design_research_agents._mcp_server"),
16                env={"PYTHONPATH": "src"},
17                timeout_s=20,
18            ),
19        ),
20        workspace_root=".",
21        enable_core_tools=False,
22    ) as runtime:
23        mcp_tools = sorted(spec.name for spec in runtime.list_tools() if spec.name.startswith("local_core::"))
24        direct_result: ToolResult = runtime.invoke(
25            "local_core::text.word_count",
26            {"text": "design research"},
27            request_id="example-mcp-minimal",
28            dependencies={},
29        )
30        if not direct_result.ok:
31            raise RuntimeError(f"MCP tool call failed: {direct_result.error!r}")
32        if not isinstance(direct_result.result, dict):
33            raise RuntimeError("MCP tool call returned non-dict payload.")
34        direct = direct_result.result
35
36    return {
37        "mcp_tool_count": len(mcp_tools),
38        "sample_tools": mcp_tools[:5],
39        "direct_result": direct["word_count"],
40    }
41
42
43def main() -> None:
44    """Run traced MCP report generation and print JSON result."""
45    # Fixed request id keeps traces and docs output deterministic across runs.
46    request_id = "example-tools-mcp-minimal-design-001"
47    tracer = Tracer(
48        enabled=True,
49        trace_dir=Path("artifacts/examples/traces"),
50        enable_jsonl=True,
51        enable_console=True,
52    )
53    report = tracer.run_callable(
54        agent_name="ExamplesMcpMinimal",
55        request_id=request_id,
56        input_payload={"scenario": "mcp-runtime-design"},
57        function=_run_report,
58    )
59    assert isinstance(report, dict)
60    report["example"] = "tools/mcp_minimal.py"
61    report["trace"] = tracer.trace_info(request_id)
62    print(json.dumps(report, ensure_ascii=True, indent=2, sort_keys=True))
63
64
65if __name__ == "__main__":
66    main()

Expected Results

Run Command

PYTHONPATH=src python3 examples/tools/mcp_minimal.py

Example output captured with DRA_EXAMPLE_LLM_MODE=deterministic (timestamps, durations, and trace filenames vary by run):

{
  "direct_result": 2,
  "example": "tools/mcp_minimal.py",
  "mcp_tool_count": 23,
  "sample_tools": [
    "local_core::bash.exec",
    "local_core::data.describe",
    "local_core::data.load_csv",
    "local_core::eval.decision_matrix",
    "local_core::eval.pairwise_rank"
  ],
  "trace": {
    "request_id": "example-tools-mcp-minimal-design-001",
    "trace_dir": "artifacts/examples/traces",
    "trace_path": "artifacts/examples/traces/run_20260222T162209Z_example-tools-mcp-minimal-design-001.jsonl"
  }
}

References