Testing, designing and shipping servers

Designing tools for models

A model only knows your tools through their names, descriptions and schemas, and it pays in tokens for every result. Ask a waiter what's good tonight and you want a recommendation, not the supplier list. The habits that work:

• Shape tools around tasks, not endpoints. Don't mirror an API's 40 endpoints as 40 tools. A model asked "how's the spring campaign doing?" does better with one campaign_report(name) tool than with a chain of list_campaigns, get_campaign and get_metrics calls.
• Name and describe for the model. Say what it does, when to use it, and what comes back. Describe each parameter's format with an example: "ISO date, e.g. 2026-10-30".
• Constrain inputs. Use enums, minimums and required fields, so wrong calls fail fast with a clear message instead of doing something odd.
• Return what's useful, concisely. Long raw JSON wastes context and buries the answer. Return the fields that matter, paginate long lists, and consider a detail parameter ("summary" or "full"). Include ids the model will need for follow-up calls.
• Make errors teach. "No campaign named 'sprng'. Did you mean 'Spring sale'?" gets fixed on the next call. Use isError results for these, not protocol errors.
• Keep the list small and stable. Fewer, distinct tools are easier for a model to choose between. A fixed order helps caching.
• Test with a model. Write a few realistic tasks, run them, and read the transcripts. The model's confusion shows you which description to fix. That's an eval, as in Phase 1.

In plain words: design tools for what people ask, and read how the model uses them.

CUSTOMERS = {"ann@shop.example": "c1"}
ORDERS = {"c1": ["o9"]}
STATUS = {"o9": "shipped"}

calls = []
def find_customer(email):
    calls.append("find_customer"); return CUSTOMERS[email]
def list_orders(customer):
    calls.append("list_orders"); return ORDERS[customer]
def get_order(order):
    calls.append("get_order"); return STATUS[order]

status = get_order(list_orders(find_customer("ann@shop.example"))[0])
print("API-shaped:", status, "after", len(calls), "tool calls")

calls.clear()
def latest_order_status(email):
    calls.append("latest_order_status")
    return STATUS[ORDERS[CUSTOMERS[email]][0]]

print("Task-shaped:", latest_order_status("ann@shop.example"), "after", len(calls), "tool call")

Packaging and finding servers

• Python servers are usually published to PyPI and run with uvx shop-mcp, which installs and runs them in an isolated environment. Node servers are published to npm and run with npx. Many are also published as container images.
• The MCP Registry is the community's central directory of public servers, a phone book that hosts and people can search. Publishing there gives yours a stable name and metadata.
• Version your server with semantic versioning, numbers like 1.4.2 whose first part goes up when something breaks. Changing a tool's name, removing a parameter or changing what it returns is a breaking change for every host and every prompt that relies on it.
• The official SDKs (Python and TypeScript are the most used, and there are others, such as C#, Java, Kotlin, Go and Rust) handle framing, transports, schemas and protocol versions. They're how most servers are built. Knowing what they do inside, which is what this phase has taught, is how you debug them.

Running a remote server

Modern MCP is stateless, which makes deployment ordinary web engineering:

• Run several copies behind a load balancer, with no sticky sessions. Any copy can answer any request.
• Put OAuth in front (last lesson), plus rate limits per user and per tool.
• Use ttlMs on list results, so clients don't hammer tools/list.
• Log to stderr (or your platform's logs) with a request id. Clients can pass OpenTelemetry trace context (traceparent) in _meta, so one trace can follow a request from the host through your server to the APIs it calls.
• Watch per-tool error rates and latency. A tool that fails 30% of the time is a design bug.

import requests

URL = "https://api.gradient.test/mcp"
GOOD = {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}

def post(method, meta, id=1, version="2026-07-28"):
    body = {"jsonrpc": "2.0", "id": id, "method": method, "params": {"_meta": meta}}
    headers = {"MCP-Protocol-Version": version, "Mcp-Method": method}
    return requests.post(URL, json=body, headers=headers, timeout=10)

r = post("resources/unknown", GOOD)
print("unknown method:", r.status_code, r.json()["error"]["code"], "(want 404, -32601)")

r = post("tools/list", {**GOOD, "io.modelcontextprotocol/protocolVersion": "1999-01-01"}, version="1999-01-01")
err = r.json()["error"]
print("bad version:", r.status_code, err["code"], err["data"]["supported"], "(want 400, -32022)")

Renames break things

Rename a street, and every map and delivery route that used the old name goes wrong. A tool's name is a public interface. Models, prompts and saved approvals all depend on it, so treat a rename as a breaking change.