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:
| Primitive | Who controls it | What it is | SDK registration (Python FastMCP) |
|---|---|---|---|
| Tools | Model-controlled | Functions the LLM can call (with host/user approval) — side effects, lookups | @mcp.tool() |
| Resources | Application-controlled | File-like data a client can read (API responses, file contents) addressed by URI | @mcp.resource(uri) |
| Prompts | User-controlled | Pre-written templates the user invokes to accomplish a task | @mcp.prompt() |
@-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:
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
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
EXAM TRAPS
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).print()-debugging a stdio server. → On stdio, stdout is the
JSON-RPC transport. Any stray write to stdout breaks the protocol. Log to stderr.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).