Building an MCP Server

Topics We'll Cover

• SDK Landscape & the Minimum Viable Server
• Tools — Schema, Structured Output, Annotations
• Resources — URIs, Content Types, Subscriptions
• Prompts — Reusable Argumented Templates
• Sampling — Borrowing the Host's Model before 2026-07-28
• Elicitation — Asking the User a Typed Question before 2026-07-28
• Multi Round-Trip Requests — How a Server Asks in 2026-07-28 2026-07-28
• Errors, Progress, Cancellation, Logging
• Testing — The MCP Inspector
• What to Take Away

SDK Landscape & the Minimum Viable Server

Anthropic publishes first-party SDKs in Python, TypeScript, Java, C#, Kotlin, Swift, Go and Ruby. They're all generated from one schema, so feature parity is good. The two you'll meet most often are Python (FastMCP) and TypeScript — we'll show both in parallel.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def forecast(region: str) -> dict:
    """24h forecast for an ISO 3166-2 region."""
    return {"tempC": 12.0,
            "summary": "light rain"}

if __name__ == "__main__":
    mcp.run()  # stdio by default

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" });

server.registerTool("forecast", {
  inputSchema: { region: z.string() },
  outputSchema: { tempC: z.number(), summary: z.string() }
}, async ({ region }) => ({
  structuredContent: { tempC: 12, summary: "light rain" },
  content: [{ type: "text", text: "London 12 C, light rain" }]
}));

await server.connect(new StdioServerTransport());

FastMCP autogenerates the input schema from Python type hints; the TS SDK uses Zod and converts to JSON Schema at registration time. Either way the wire-format is identical — pick by language preference, not by feature.

Tools — Schema, Structured Output, Annotations

A tool exposes one function the model can call. Three pieces matter: the input schema, the output schema (since 2025-06-18) and the annotations that classify the tool's effects.

Anatomy of a Tool descriptor

{
  "name": "create_issue",
  "title": "Create GitHub Issue",
  "description": "Open a new issue on a GitHub repository.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "repo":  { "type": "string", "pattern": "^[^/]+/[^/]+$" },
      "title": { "type": "string", "minLength": 1, "maxLength": 256 },
      "body":  { "type": "string" },
      "labels":{ "type": "array", "items": { "type": "string" } }
    },
    "required": ["repo","title"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "number": { "type": "integer" },
      "url":    { "type": "string", "format": "uri" }
    },
    "required": ["number","url"]
  },
  "annotations": {
    "title":           "Create GitHub Issue",
    "readOnlyHint":    false,
    "destructiveHint": false,
    "idempotentHint":  false,
    "openWorldHint":   true
  }
}

The five annotation hints

Returning a result

A successful tools/call returns three things: an array of content blocks (text/image/audio/resource_link) for the model, optional structuredContent for downstream code, and isError: false. A tool-level failure flips isError to true and puts the explanation in content.

{
  "content": [
    { "type": "text",
      "text": "Created issue #42: 'Bug in login flow'." },
    { "type": "resource_link",
      "uri":  "https://github.com/me/repo/issues/42",
      "name": "Issue #42" }
  ],
  "structuredContent": { "number": 42,
                         "url": "https://github.com/me/repo/issues/42" },
  "isError": false
}

Resources — URIs, Content Types, Subscriptions

Resources are the read side of MCP. The model can pull a file's contents, a database row, a Confluence page — addressed by URI — without you having to write a tool wrapper for every read pattern.

Two flavours: static and templated

Reading a resource

// → client
{"jsonrpc":"2.0","id":7,"method":"resources/read",
 "params":{"uri":"db://users/42/profile"}}
// ← server
{"jsonrpc":"2.0","id":7,"result":{
  "contents":[{
    "uri":"db://users/42/profile",
    "mimeType":"application/json",
    "text":"{\"id\":42,\"name\":\"Ada\",\"role\":\"admin\"}"
  }]
}}

Each entry in contents carries either a UTF-8 text field or a base64 blob for binary types — PDFs, images, audio. The mimeType is used by the host to decide rendering and by the model to disambiguate parsing.

Subscriptions — pushing changes before 2026-07-28

If the server declared resources.subscribe: true at handshake, the client can ask to be told when a specific URI changes:

// → client
{"jsonrpc":"2.0","id":8,"method":"resources/subscribe",
 "params":{"uri":"file:///project/README.md"}}

// ← server, later when the file changes
{"jsonrpc":"2.0","method":"notifications/resources/updated",
 "params":{"uri":"file:///project/README.md"}}

Source: MCP specification 2026-07-28 — Subscriptions; Resources (accessed 2026-10-08).

Prompts — Reusable Argumented Templates

Prompts are the third server primitive: parameterised text templates the user can invoke explicitly — typically as slash commands in the host UI. They differ from tools in two ways: they're user-driven, not model-driven, and they produce messages to insert, not results to act on.

from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.prompts import base

mcp = FastMCP("reviewer")

@mcp.prompt()
def review_pr(repo: str, pr_number: int, focus: str = "correctness"):
    """Run a structured PR review."""
    return [
        base.UserMessage(
            f"Review PR #{pr_number} on {repo}. "
            f"Focus on {focus}. Use the ‘diff’ tool first, "
            f"then comment via ‘create_review’."),
    ]

The wire view

{"jsonrpc":"2.0","id":11,"result":{
  "prompts":[{
    "name":"review_pr",
    "description":"Run a structured PR review.",
    "arguments":[
      {"name":"repo","required":true},
      {"name":"pr_number","required":true},
      {"name":"focus","required":false}
    ]
  }]
}}

// → client
{"jsonrpc":"2.0","id":12,"method":"prompts/get","params":{
  "name":"review_pr",
  "arguments":{"repo":"acme/api","pr_number":"341","focus":"security"}}}
// ← server
{"jsonrpc":"2.0","id":12,"result":{
  "messages":[{
    "role":"user",
    "content":{"type":"text",
      "text":"Review PR #454a29 on acme/api. Focus on security. ..."}
  }]
}}

Sampling — Borrowing the Host's Model before 2026-07-28

Sampling inverts the usual direction. The server calls sampling/createMessage, asking the client's LLM to produce a completion. Lets a server build agentic behaviour without bringing its own model — and lets the user keep control of which model is used and how much is spent.

{"jsonrpc":"2.0","id":99,"method":"sampling/createMessage","params":{
  "messages":[
    {"role":"user","content":{"type":"text",
      "text":"Summarise this issue thread in three bullets."}}
  ],
  "modelPreferences":{
    "hints":[{"name":"claude-sonnet-4"}],
    "intelligencePriority":0.6,
    "speedPriority":0.3,
    "costPriority":0.1
  },
  "systemPrompt":"You are a precise issue triager.",
  "maxTokens":400,
  "temperature":0.0,
  "includeContext":"thisServer"
}}

How the host gates this

• The user MUST approve. Sampling can leak data and cost real money — the host typically prompts on first use per server, with an “always allow” option per tool family.
• Model preferences are hints, not contracts. The host picks the actual model from what's available given user policy.
• includeContext can be none, thisServer, or allServers — controls whether messages from other connected servers' contexts get folded in.

Source: MCP specification 2026-07-28 — Sampling; Deprecated features (accessed 2026-10-08).

Elicitation — Asking the User a Typed Question before 2026-07-28

Elicitation, standardised in 2025-06-18, lets a server pause and ask the user a structured question mid-flow. The server sends a JSON Schema describing the requested input; the host renders it as a form; the user accepts, declines, or cancels.

{"jsonrpc":"2.0","id":21,"method":"elicitation/create","params":{
  "message":"Confirm shipping address for order #4a452e11.",
  "requestedSchema":{
    "type":"object",
    "properties":{
      "name":   { "type":"string" },
      "street": { "type":"string" },
      "city":   { "type":"string" },
      "zip":    { "type":"string", "pattern":"^[0-9]{5}$" },
      "country":{ "type":"string", "enum":["US","UK","DE","FR"] }
    },
    "required":["name","street","city","zip","country"]
  }
}}

{"jsonrpc":"2.0","id":21,"result":{
  "action":"accept",
  "content":{
    "name":"Ada Lovelace",
    "street":"1 Analytical Way",
    "city":"London",
    "zip":"10001",
    "country":"UK"
  }
}}

The three actions

Source: MCP specification 2026-07-28 — Elicitation; Key changes (accessed 2026-10-08).

Multi Round-Trip Requests — How a Server Asks in 2026-07-28 2026-07-28

In 2026-07-28 a server never sends a request to the client. When tools/call, prompts/get or resources/read needs more input, the server finishes that request with an interim result of resultType: "input_required". The client gathers the answers (from the user, or its model) and retries the original request with a new ID, carrying inputResponses and echoing requestState.

// → client: tools/call, id 1 (_meta omitted for brevity)
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"ship_order","arguments":{"order":"4a452e11"}}}
// ← server
{"jsonrpc":"2.0","id":1,"result":{
  "resultType":"input_required",
  "inputRequests":{
    "address":{
      "method":"elicitation/create",
      "params":{"mode":"form",
        "message":"Confirm shipping address for order #4a452e11.",
        "requestedSchema":{"type":"object",
          "properties":{"city":{"type":"string"},"zip":{"type":"string"}},
          "required":["city","zip"]}}}},
  "requestState":"<opaque, integrity-protected by the server>"
}}

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"ship_order","arguments":{"order":"4a452e11"},
  "inputResponses":{
    "address":{"action":"accept","content":{"city":"London","zip":"10001"}}},
  "requestState":"<echoed unchanged>"}}
// ← server
{"jsonrpc":"2.0","id":2,"result":{"resultType":"complete",
  "content":[{"type":"text","text":"Order 4a452e11 shipped."}],"isError":false}}

Source: MCP specification 2026-07-28 — Multi round-trip requests; Elicitation (accessed 2026-10-08).

Errors, Progress, Cancellation, Logging

Tool errors vs JSON-RPC errors

The single most common server-side mistake. A tool that ran but failed (“the API returned 401”) returns a normal JSON-RPC result with isError: true:

{"jsonrpc":"2.0","id":3,"result":{
  "content":[{"type":"text","text":"Auth failed: 401 Unauthorized. Refresh your token and retry."}],
  "isError":true
}}

JSON-RPC errors are reserved for protocol-layer problems — bad params, unknown method, malformed JSON. The reason: the model needs to see tool failures to course-correct; protocol errors short-circuit before the model gets a turn.

Progress notifications

Any long-running request (tools/call, resources/read) can include a progressToken in params._meta. The server then emits notifications/progress with the same token at intervals.

{"jsonrpc":"2.0","method":"notifications/progress","params":{
  "progressToken":"abc-7",
  "progress":0.45,
  "total":1.0,
  "message":"Indexing 45 of 100 files"
}}

Cancellation

before 2026-07-28 Either side can cancel an in-flight request by sending a notification with the request ID. The receiver SHOULD stop work and SHOULD NOT send the response. Initialize cannot be cancelled.

2026-07-28 Only the client cancels requests. On Streamable HTTP, closing the request's SSE stream is the cancellation; on stdio the client sends notifications/cancelled. A server sends notifications/cancelled only to end a subscriptions/listen stream.

{"jsonrpc":"2.0","method":"notifications/cancelled","params":{
  "requestId":42,
  "reason":"User pressed Esc"
}}

Logging before 2026-07-28

In 2026-07-28 Logging is deprecated and logging/setLevel is removed: a client puts io.modelcontextprotocol/logLevel in a request's _meta, and the server MUST NOT emit notifications/message for requests without it. Suggested migration: log to stderr (stdio) or OpenTelemetry. Before 2026-07-28: if the server declared logging capability, the client can call logging/setLevel to set a syslog-style level (debug, info, notice, warning, error, critical, alert, emergency). The server emits structured records via notifications/message:

{"jsonrpc":"2.0","method":"notifications/message","params":{
  "level":"warning",
  "logger":"db.pool",
  "data":{"event":"slow_query","durationMs":1840,"sql":"SELECT ..."}
}}

Source: MCP specification 2026-07-28 — Cancellation; Logging; Deprecated features (accessed 2026-10-08).

Testing — The MCP Inspector

The @modelcontextprotocol/inspector Node tool is the official conformance harness. It launches your server (stdio or HTTP), exercises every primitive interactively, and shows the raw JSON-RPC traffic. If your server doesn't pass Inspector smoke-tests, no host will be able to use it.

# with no arguments — opens a UI on http://localhost:6274
npx @modelcontextprotocol/inspector

# launching your server directly
npx @modelcontextprotocol/inspector \
    uvx mcp-server-sqlite --db-path /tmp/test.db

# a Streamable HTTP server
npx @modelcontextprotocol/inspector \
    --transport http http://localhost:3000/mcp

What to exercise

What to Take Away

• Start tiny. A 30-line server with one @mcp.tool is a complete, useful MCP server.
• Schema everything. Input schema is non-negotiable; output schema makes downstream code possible; annotations let hosts make sane UX decisions.
• Resources for reads, tools for writes. Don't conflate them. A read-only tool is almost always a resource in disguise.
• Tool failures live in result.isError. JSON-RPC errors are for protocol problems only.
• Sampling and elicitation are first-class. A server can ask the model (sampling) or the user (elicitation) for help — with the host gating both. In 2026-07-28 it asks by returning input_required and the client retries; Sampling (and Roots, Logging) are deprecated.
• Progress and cancellation come for free. Use them on anything slower than a few hundred ms.
• Pass Inspector before you ship. If you don't, your users will be the conformance test.