D2 · Tool Design & MCP › Cluster 7 · Building & Consuming MCP Servers

7.1 · Building a Server (SDK)

Define tools, resources, prompts

CONCEPT An MCP server exposes three primitives over a transport

A Model Context Protocol server is a small program that advertises capabilities to any MCP host (Claude Desktop, Claude Code, the Messages API connector, your own client). You don't write a protocol parser — the official SDKs handle the JSON-RPC wire format. You register handlers and pick a transport. Per the spec, a server can expose three kinds of capability:

PrimitiveWho controls itWhat it isSDK registration (Python FastMCP)
ToolsModel-controlledFunctions the LLM can call (with host/user approval) — side effects, lookups@mcp.tool()
ResourcesApplication-controlledFile-like data a client can read (API responses, file contents) addressed by URI@mcp.resource(uri)
PromptsUser-controlledPre-written templates the user invokes to accomplish a task@mcp.prompt()
🔑 Tools are the primitive Claude decides to call on its own; resources are pulled in by the client/user (e.g. an @-mention); prompts are slash-command templates the user triggers. Get the primitive right and the host wires it into the correct UX.

CONCEPT FastMCP infers the schema; you pick the transport

The Python mcp package ships FastMCP, which reads your function's type hints and docstring to auto-generate the tool's name, description, and JSON input_schema — no hand-written schema. The TypeScript SDK's McpServer.registerTool takes a Zod inputSchema instead. Either way, the same server code runs over two transports:

stdio — the server runs as a local child process; the host speaks JSON-RPC over stdin/stdout. Best for local tools with filesystem/system access. Streamable HTTP — the server is a remote HTTP endpoint; required for anything the Messages API connector (7.2) or a hosted client reaches by URL.
⚠️ On stdio, stdout is the JSON-RPC channel — never print() to it. Log to stderr only, or you corrupt the protocol stream (see 7.5).

DIAGRAM Register handlers → run on a transport → host calls them

flowchart TD DEF["Your server code"] --> T["@mcp.tool()
model-controlled action"] DEF --> R["@mcp.resource(uri)
readable data"] DEF --> P["@mcp.prompt()
template"] T --> RUN["mcp.run(transport=...)"] R --> RUN P --> RUN RUN -->|"stdio: local child proc"| HOST1["🟢 Claude Desktop / Claude Code"] RUN -->|"Streamable HTTP: remote URL"| HOST2["🔵 Messages API connector / hosted client"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef net fill:#cce5ff,stroke:#4a90d9,color:#0b3d66; class HOST1 ok; class HOST2 net;

CODE A minimal server: Python FastMCP and TypeScript

Same server, two SDKs. FastMCP infers the schema from hints + docstring; the TS SDK uses an explicit Zod schema. Both run over stdio for local use.

# Python — pip install "mcp[cli]"
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

# TOOL — model-controlled; schema inferred from type hints + docstring
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get the weather forecast for a location."""
    return await fetch_forecast(latitude, longitude)

# RESOURCE — application/user-controlled, addressed by URI
@mcp.resource("config://units")
def units() -> str:
    return "imperial"

# PROMPT — user-controlled template
@mcp.prompt()
def trip_brief(city: str) -> str:
    return f"Summarize the weather outlook for {city} for a weekend trip."

if __name__ == "__main__":
    mcp.run(transport="stdio")   # or a Streamable HTTP transport for remote
// TypeScript — npm install @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "weather", version: "1.0.0" });

server.registerTool(
  "get_forecast",
  {
    description: "Get the weather forecast for a location",
    inputSchema: {
      latitude:  z.number().min(-90).max(90),
      longitude: z.number().min(-180).max(180),
    },
  },
  async ({ latitude, longitude }) => ({
    content: [{ type: "text", text: await fetchForecast(latitude, longitude) }],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

TRADE-OFFS Promoting an action to a tool vs. leaving it as a resource/prompt

✅ Expose as a tool

  • The model can invoke it autonomously mid-task
  • Auto-schema means less boilerplate to maintain
  • Host can gate/approve each call individually

⚠️ Expose as a resource or prompt

  • Resource: read-only, pulled in by user/app — not something the model triggers on its own
  • Prompt: a user-launched template, not an autonomous capability
  • Wrong choice → the capability shows up in the wrong place in the host UI
Rule of thumb: if the model should decide when to run it, it's a tool. If the user supplies context or launches a workflow, it's a resource or prompt.

EXAM TRAPS

Trap: "MCP servers only expose tools." → The spec defines three primitives: tools, resources, and prompts. Tools are model-controlled; resources are app/user-controlled data; prompts are user-launched templates.
Trap: Writing the JSON input_schema by hand in FastMCP. → FastMCP infers the schema from Python type hints and the docstring. The docstring becomes the tool description, so write it for the model (2.1).
Trap: print()-debugging a stdio server. → On stdio, stdout is the JSON-RPC transport. Any stray write to stdout breaks the protocol. Log to stderr.
Trap: Assuming one transport fits everywhere. → stdio is for local child-process servers; a server reached by the Messages API connector (7.2) or a hosted client must run over Streamable HTTP at a public URL.

PRACTICE

Q1 · What are the three primitives an MCP server can expose, and who controls each?

Tools (model-controlled functions the LLM calls), resources (application/user-controlled file-like data read by URI), and prompts (user-launched templates). The distinction determines how the host surfaces each capability.

Q2 · In FastMCP, where does a tool's input schema and description come from?

FastMCP generates them automatically from the function's type hints (the schema) and its docstring (the description). You don't hand-write JSON schema — which is why the docstring quality matters.

Q3 · You need a server the Messages API connector can call. Which transport, and why not stdio?

Streamable HTTP at a public HTTPS URL. stdio only works for a local child process the host spawns; a remote/hosted consumer reaches the server by URL over HTTP, and the connector cannot launch a local stdio process (7.2).