Skip to content

English · Español

Phase 31 — Tool Use & the Model Context Protocol (MCP)

Requires: 30 — Structured Generation & Constrained Decoding Teaches: tool-use · function-calling · mcp · json-schema · json-rpc Jump to any chapter from the phase reference index.

Chapter map

Pre-written per A12. This phase entry exists before Borja begins study. Theory and lab problem statements are stable drafts; solutions are written just-in-time at phase open.

🇪🇸 "Function calling", "tool use", "agentic" — vocabulario para una sola idea: el modelo emite JSON que dispara una función Python. La gracia de MCP es estandarizar cómo ese JSON se descubre, valida y enruta. Esta fase construye el plumbing desde cero.

Goal

Build the tools layer of the grammar-tutor stack: four typed Python functions (conjugate, lookup_irregular_verb, lookup_spanish, check_subject_verb_agreement) that operate on the §A13 universe, plus a minimal MCP server/client pair that exposes them over JSON-RPC stdio. By phase end, Borja can send a JSON-RPC message from a client process to a server process and get back a typed result — and explain exactly which bytes flow over the pipe.

This phase introduces the new module src/miniagent/ (tools + MCP machinery). Phase 32 extends it with the agent loop, memory, and sandbox.

Read order

  1. theory/00-motivation.md — why the agent loop needs tools at all; the limits of a pure-LM system.
  2. theory/01-function-calling-formats.md — survey: OpenAI-style, Anthropic-style, raw JSON-Schema. What each gets right and wrong.
  3. theory/02-mcp-architecture.md — MCP's three-part shape (server, client, transport); the four wire verbs we care about (initialize, tools/list, tools/call, notifications/...); JSON-RPC 2.0 framing.
  4. theory/03-authn-authz.md — permission models, the local-trust assumption stdio gives us, what changes when we go HTTP.
  5. lab/00-typed-tools.md — write the four tools as plain Python functions with JSON-Schema descriptors.
  6. lab/01-mcp-server.md — hand-rolled JSON-RPC stdio server exposing the tools.
  7. lab/02-mcp-roundtrip.md — client spawns server, lists tools, calls one.
  8. lab/03-mask-driven-toolcall.md — connect Phase 30's JSONSchemaMask to tool-call argument generation. End-to-end.

solutions/ is empty during pre-write — populated at phase open.

Definition of Done

See PHASE_31_PLAN.md §6. Briefly:

  • 4 tools implemented and tested against the §A13 truth table.
  • MCP server + client round-trip succeeds on stdio.
  • A model-generated tool-call argument blob, produced under JSONSchemaMask, dispatches correctly.
  • src/miniagent/BLUEPRINT.md reviewed and matches the landed API.

What this phase intentionally does NOT cover

  • The agent loop. That's Phase 32. Phase 31 stops at "client can call a tool"; there is no planner, no memory, no multi-step reasoning.
  • Sandboxing. Phase 32. The tools in Phase 31 are pure Python with no side effects; sandbox would be ornamental.
  • HTTP/SSE transports. Phase 33 (src/miniserve/) will expose the agent over HTTP; Phase 31 stays on stdio because that's the smallest correct transport.
  • Anthropic's mcp SDK in production. Phase 31 hand-rolls the protocol to see it. A stretch goal ports to the SDK as a comparison.
  • Tool-call streaming. Tools are synchronous request/response. Streaming tools (e.g., a database query that emits rows progressively) are out of scope.
  • Authn/authz beyond local-trust. We document the threat model and stop. Phase 37 revisits.

Phase 31's scope is: typed tools, MCP stdio round-trip, mask-driven tool-call generation. Nothing more.

Further reading

Optional — enrichment, not required to pass the phase.