Connecting to Reality: MCP and System Integration · Milestone Companion: One Server, Every Client

Date: October 19, 2026 · Path: Agent Builder · Stage s4

What this milestone asks

Pick one system you actually use — a personal ledger, your notes, a ticket tracker, a home inventory — and write an MCP server for it. Then connect a real MCP client (Claude Desktop, VS Code, or Cursor) and complete a genuine task end-to-end through natural language: "what did I spend on groceries last month," answered by your server querying your data.

Scope it tightly. Three to five tools, read-only first: list_accounts, search_transactions, monthly_summary in the ledger example. A write tool (add_transaction) is welcome only after the read tools work, and only with a confirmation step. The deliverable is not the code — it is the moment a client you did not write discovers your tools, calls them correctly, and returns an answer it could not have produced alone.

Why this milestone

The Model Context Protocol's own documentation describes it as "like a USB-C port for AI applications" — an open standard, supported by Claude, VS Code, Cursor, and a growing list of clients. The marketing analogy actually understates the engineering point: implement your system once as an MCP server, and every MCP-capable client — present and future — can use it. For working engineers, wrapping an internal API as an MCP server is currently the most practical adoption path into agent systems, because it inverts the usual integration economics: the tool author ships once, and every host application benefits.

The deeper lesson is that tools are permissions. The moment your ledger becomes callable by a model, every design decision turns into a security decision: which credentials the server holds, whether the database user can write, what a tool returns when asked for something sensitive. Least privilege, read-only by default, second confirmation for sensitive operations — these are not enterprise affectations; they are the shape of any tool connected to reality. You will also meet context engineering in its practical form: what a tool returns is the model's entire knowledge of your system, and it should read like onboarding documentation for a brilliant new hire — precise, layered, and free of noise.

How to use the resources

Concepts first: the official MCP documentation (modelcontextprotocol.io). Read the architecture and concepts pages before writing any code. Understand servers, clients, tools, resources, and prompts as distinct primitives, and note the transport options — most first servers are local, and that is fine.
Design by reading source: the official MCP servers repository. The reference servers (filesystem, git, and friends) are the best design school available. Read one that resembles your system; study its tool granularity, naming, descriptions, and error handling before you design your own.
Client-side: Anthropic's MCP tutorial covers connecting from the Claude side, which is likely your first test client.
Theory in parallel: the tool-use lectures of the Berkeley LLM Agents MOOC — videos remain on the syllabus page — give you the research context for why tool design dominates model choice. If you work in Chinese, 技术爬爬虾's AI-tools videos are a pragmatic complement.
Then build, in this order: a minimal server the client can see; one read tool against real data; the remaining read tools; then, optionally, one confirmed write.

Common failure modes

Write tools first. The first tool you expose is a mutation, tested against production data. Start read-only; treat write access as a separate milestone with its own review.
Over-privileged credentials. The server uses your personal admin token because it was convenient. Create a least-privilege credential — ideally a read-only database user — before the first client handshake.
Database dumps as responses. Returning five hundred rows of raw JSON because the tool can. Tools should answer the questions they exist for, in compact, LLM-readable text, with explicit limits.
Tool descriptions written for humans. Name and description are the model's entire basis for choosing the tool. Write what it does, when to use it, what each parameter means, and what the return looks like.
Silent failures and stack traces. An unhandled exception surfacing as garbage in the client. Convert errors into actionable messages the model can reason about: "no account named X; available accounts: …"
Secrets in the transcript. API keys or personal data echoed into tool results — which means into the model's context and the client's logs. Audit your responses as if they were public.
Testing only with curl. The milestone is client-verified: if no real MCP client has discovered and called your tools, it is not done.

Acceptance checklist

A real MCP client completes the handshake, lists your tools, and calls them — visible in the client's own UI.
Three to five tools, majority read-only; any write operation requires explicit user confirmation in the client.
Every tool description states purpose, when-to-use, parameter meanings, and return shape.
Responses are compact, LLM-readable text with enforced limits — no raw table dumps.
Server credentials are least-privilege; read-only where the tool is read-only.
Error paths return useful messages, and you have watched the model recover from one.
One genuine task completed end-to-end via natural language, with the trace to show for it.

Going further

Move beyond tools: expose resources (your notes as browsable content) and prompts (reusable workflows shipped with the server). Look at remote deployment and authentication once the local version is solid. Read a few third-party servers critically and ask what you would revoke. And keep every trace from your testing — Stage 5 turns this working server into a measured system.