Chapter 7 — Capstone: A Worked Intelligent Assistant on a Custom FastMCP Tool Server

1. System Design and Requirements

Before a line of code, we design. The capstone case is Sentinel, an on-call DevOps incident-triage assistant: an engineer types "the checkout API looks unhealthy" and Sentinel pulls error-rate metrics, greps logs, checks for a recent deploy, reads the runbook, and proposes a first mitigation — all through tools on a custom FastMCP server. It is a good capstone because it needs all three MCP capability kinds and has real auth, idempotency, and safety concerns.

The wire between the tiers is MCP, a standardized JSON-RPC 2.0 channel. Because it is standardized, the same Sentinel server would answer Cursor or VS Code just as happily as the SDK client. Think of the tiers as an emergency dispatch center: Claude is the dispatcher (judgment, never drives a truck), the FastMCP server is the fleet of trucks (real-world reach), and MCP is the radio protocol every unit speaks.

Figure 7.1 — Sentinel component diagram

Figure 7.2 — End-to-end data flow (one turn)

One request traces as: prompt + tool definitions → Claude emits a tool_use → client relays to the server → server executes the decorated function → returns an MCP tool result carrying the matching tool_use_id → result appended and passed back → Claude either issues another tool call or generates the final triage summary. This is the same agentic loop from Chapter 5, but now every step crosses the MCP boundary.

Deciding: tool, resource, or skill?

The heuristic: if the model supplies arguments and expects a fresh computed answer, it is a tool; if it just reads a stable body of data, it is a resource; if you are encoding how to sequence the tools, it is a skill. Sentinel's surface is therefore five tools, two resources, one skill — small on purpose.

2. Building the FastMCP Tool Server

Sentinel exposes five tools — get_error_rate, search_logs, get_recent_deploys (read-only), and page_oncall, open_incident (mutating) — plus two resources (catalog://services/{service} and runbook://{service}). Read-only tools return computed answers; resources return reference data the model dereferences by URI.

Idempotency is first-class here because Sentinel takes real-world actions. FastMCP may retry on a transient blip and the SDK may re-issue a call — but paging a human twice is genuine harm. So page_oncall is described as mutating and non-idempotent in effect, gated to sev1/sev2, and made safe on retry by an idempotency_key the backing store dedupes on. open_incident is mutating but idempotent: the same key returns the same incident.

Both modes are one flag: mcp.run() defaults to stdio, while SENTINEL_TRANSPORT=http switches to mcp.run(transport="streamable-http", host="0.0.0.0", port=8080). HTTP servers run as ASGI apps, scaled with multiple workers and fitted with logging middleware. Before spending a single token, launch the server under the Inspector (npx @modelcontextprotocol/inspector python server.py), confirm the schemas (e.g. page_oncall shows severity as an enum of sev1|sev2|sev3), and check the resources resolve.

3. Building the Assistant Client

The client is pure orchestration. Its system prompt encodes Sentinel's identity and guardrails ("Only page_oncall for sev1/sev2, only after gathering evidence, and always with a stable idempotency_key. Never invent service names."). Two details carry the Chapter 6 security model: stdio credentials pass through env, and — the zero-trust point — connecting to a server grants no tools at all. The docs recommend allowedTools over permissionMode because modes like acceptEdits do not auto-approve MCP tools and bypassPermissions is too broad.

The multi-turn loop streams message events: it raises immediately if any server's init status is not connected, prints text blocks to the operator, logs every tool_use block whose name starts with mcp__, and inspects the final result subtype. Connection failures surface in init and as timeouts (a cold-starting prod server may need MCP_TIMEOUT=60000); tool-execution failures come back as error_during_execution and should be surfaced to the operator, not hidden.

The payoff of the Section 2 design: because mutating tools carry idempotency keys, a client retry of page_oncall after a network blip is safe — the store dedupes it. Idempotency at the server makes retries at the client boringly safe.

4. Evaluation, Hardening, and Next Steps

Because signals already exist in the SDK, evals assert against the exact events it surfaces — for instance, a "checkout looks fine" scenario must call get_error_rate but must not call page_oncall, and must end in success. Server-side, the FastMCP HTTP ASGI middleware logs every invocation; together with the client's tool_use logging, you get both sides of every call — a distributed trace of each triage.

Figure 7.3 — Failure-mode to guardrail mapping

Figure 7.4 — Production deployment topology

Sentinel extends along natural seams: a single intent-grouped triage_incident(service) composite that internally runs the error-rate → logs → deploys sequence; sub-agents, one per suspected service, coordinated by a synthesizer (Chapter 5's multi-agent pattern); and more servers — the standardized MCP wire means a second server plugs in with another mcp_servers entry and its own allowlist. The lesson of the capstone: a production assistant is less about clever prompting and more about disciplined composition — the right capability in the right layer, behind the right guardrail.