Task statement 8.2 · Tools and MCPs

8.2 · MCP Server Development

Shelfwise, the course example, reaches its stock feed only through stock_mcp, a small Python MCP server whose one tool is stock_lookup. MCP server development decides what that server offers, how the agent reaches it, and where it runs.

Why it's tested

The tempting design makes every capability an MCP tool and every server a web service. It fails because a tool lets the model decide when it is used, and a network endpoint adds sign-in and exposure that a server launched beside its one client never needed.

KnowledgeClient vs. server

MCP, the Model Context Protocol, has three roles. The host is the application that holds the conversation, such as Claude Code. Each client it creates exchanges JSON-RPC messages with one server. In revision 2026-07-28, current as of 2026-10-05, every request carries the client's capabilities, the optional features it supports, and server/discover returns the server's. Revisions up to 2025-11-25 negotiated them once, in an initialize handshake. In Shelfwise, the Agent SDK runs Claude Code as a subprocess that is host and client, and stock_mcp is the server.

KnowledgeServer authoring: tools, resources and prompts

Server authoring starts with choosing a primitive for each capability, because each one has a different controller. A server must advertise every primitive it implements. A tool is model-controlled, so Claude decides from its description when to call it. An MCP resource is application-controlled content at a URI, so the application or the user decides what reaches the model. An MCP prompt is a user-controlled template with arguments, usually started by typing a slash and its name.

Tool · the model decides

Called with tools/call when its description fits. A failure is a normal result with isError set to true (8.1).

Resource · the application decides

Listed with resources/list, read by URI, and attached by the host or picked by the user.

Prompt · the user decides

Fetched with prompts/get and arguments; Claude Code runs each as /mcp__server__prompt.

Official SDKs handle the protocol, with TypeScript, Python, C#, Go, Rust and Ruby in Tier 1. In Python, the MCPServer class, named FastMCP before SDK v2, turns a function's type hints and docstring into a definition. In TypeScript, McpServer offers registerTool.

KnowledgeCommunication patterns: stdio, Streamable HTTP and sockets

stdio (standard input and output) is the transport in which the client launches the server as a subprocess and the two exchange newline-delimited JSON-RPC messages over its stdin and stdout. The server may log to stderr, but it must write nothing to stdout except MCP messages, so a stray print() corrupts the stream. Streamable HTTP is the transport for a server running as its own process for many clients: the client POSTs each message to one MCP endpoint, and the server replies with JSON or an SSE stream scoped to that request (5.2). That server must check the Origin header to block DNS rebinding, a trick that lets a web page reach a local server.

Interactive · one tool call on each transport

One tool call on three transports, each read from top to bottom. stdio, Shelfwise's stock server: the client launches python -m stock_mcp as a subprocess with credentials in env; the client writes the tools/call request as one line to the server's stdin; the server writes the result as one line to stdout and nothing else; the server writes its logs to stderr, never print to stdout; the client closes stdin and the server exits. Same machine, credentials from the environment. Streamable HTTP: the server is already running with one endpoint, /mcp; the client POSTs each message with a bearer access token; the server checks the Origin header and the token and answers 403 if Origin is invalid; the server replies with one JSON object or an SSE stream scoped to that request; the next message is a new POST, with no protocol session. Over the network, with OAuth 2.1 authorization. Custom transport over a socket: the server listens on a Unix socket or TCP port; the client connects, which is not a standard transport; the client writes one line, reusing stdio framing; the server writes one line back, the same JSON-RPC messages; the client closes the connection, and the transport documents its own connection and cancellation rules. Both ends must support it. stdio: stock_mcp TIME launch a subprocess python -m stock_mcp + env one line to stdin THE tools/call REQUEST one line to stdout THE RESULT, NOTHING ELSE logs to stderr NEVER print() TO stdout close stdin THE SERVER EXITS same machine CREDENTIALS FROM env Streamable HTTP TIME server already running ONE ENDPOINT: /mcp POST each message BEARER ACCESS TOKEN check Origin, token 403 IF Origin IS INVALID reply: JSON or SSE SCOPED TO THIS REQUEST next message: new POST NO SESSION (2026-07-28) over the network OAuth 2.1 AUTHORIZATION Custom: a socket TIME listen on a socket UNIX SOCKET OR TCP connect NOT A STANDARD TRANSPORT write one line REUSE THE stdio FRAMING write one line back SAME JSON-RPC MESSAGES close the connection DOCUMENT CONNECT AND CANCEL custom transport BOTH ENDS MUST SUPPORT IT

Choose how the client reaches the server.

stdio: the client launches the server as its own subprocess and passes credentials in env. Each message is one line on stdin or stdout, so the server writes nothing else to stdout and logs to stderr. Closing stdin ends the server. Shelfwise's stock_mcp runs this way.

Streamable HTTP: the server is already running as a web service with one endpoint. Each message is its own POST with an access token, the server checks Origin and the token, and the reply is one JSON object or an SSE stream for that request only.

Custom transport over a socket: not one of the two standard transports. The specification says a Unix socket or TCP link should reuse stdio's one-message-per-line framing, and the transport should document how it connects and cancels. Both ends must support it.

Each column reads downward: blue is the client's step, amber the server's.

More precise than the guide. The guide names "sockets", but specification revision 2026-07-28 defines only two standard transports, stdio and Streamable HTTP (as of 2026-10-05). A Unix domain socket or TCP connection can carry a custom transport, which should reuse stdio's newline-delimited framing. Claude Code's "type": "ws" WebSocket servers are also outside the standard (5.2). Exam answer: the standard transports are stdio and Streamable HTTP, and a socket carries a custom transport.

KnowledgeDeployment

Deployment follows the transport: a stdio server ships as a command that each host launches, and the specification tells it to take credentials from its environment. A Streamable HTTP server is a shared web service, so it should check callers. When it does, MCP authorization over HTTP is OAuth 2.1, with access tokens the client obtains for the user (7.4). Shelfwise's server shares the service's container, so the service launches it over stdio. Code declares it, because setting_sources=[] skips .mcp.json:

mcp_servers={"stock": {"command": "python", "args": ["-m", "stock_mcp"],
    "env": {"STOCK_FEED_URL": os.environ["STOCK_FEED_URL"],
            "STOCK_FEED_KEY": os.environ["STOCK_FEED_KEY"]}}}

KnowledgeIntegration with Claude applications

Integration differs in registration and in which primitives reach Claude. The Agent SDK names each tool mcp__<server>__<tool>, so Shelfwise's tool is mcp__stock__stock_lookup (1.2). The MCP connector gives a Messages API request a remote server's tools without an MCP client of your own.

Agent SDK

The mcp_servers option takes stdio, HTTP, SSE or in-process sdk servers. Claude reads resources with built-in tools, which tools=[] removes.

Claude Code

Added with claude mcp add at local or project scope (7.4), or user scope, with resources by @server:protocol://path and prompts as commands.

MCP connector

Beta header mcp-client-2025-11-20, mcp_servers plus an mcp_toolset. Public HTTP servers and tool calls only.

Claude Desktop

Local stdio servers in claude_desktop_config.json, and remote ones as custom connectors whose resources and prompts attach to a message.

SkillWorked example: a feed check, tool or resource?

To see when the feed last updated while fixing its client, each engineer runs the server in Claude Code with claude mcp add stock --env STOCK_FEED_URL=… --env STOCK_FEED_KEY=… -- python -m stock_mcp. A draft added a second tool, feed_status. Claude's pull-request review flagged two costs in the service: the definition would join every request's cached ≈6,000-token prefix, and Claude could choose the tool in a staff chat. The cause was the primitive, because engineers, not Claude, decide when feed status matters:

mcp = MCPServer("stock")               # Python SDK, run over stdio
@mcp.tool()                            # draft: Claude decides, in every chat
@mcp.resource("stock://feed-status")   # merged: an engineer attaches it
def feed_status() -> str:
    log.info("feed status read")       # stderr; stdout carries only MCP
    return f"feed {feed.time:%H:%M}, {feed.count} products"

An engineer now types @stock:stock://feed-status in Claude Code. Claude in the service cannot read the stock://feed-status resource, because tools=[] removes the tools that list and read resources, and stock_lookup stays the only definition in the prefix.

Before adding a capability to an MCP server, ask: who decides when it is used? Claude, from the request → a tool. The application, or a person attaching content → a resource. A person starting a fixed workflow → a prompt.
Takeaway
  • A stdio server writes only MCP messages to stdout and its logs to stderr.
  • The MCP connector uses only tools from public HTTP servers, while Claude Code and Claude Desktop also offer resources and prompts.
  • Revision 2026-07-28 sends capabilities with every request, with an optional server/discover. Revisions up to 2025-11-25, which the exam may assume, negotiate them once in an initialize handshake.

check yourself

0 / 3 answered

A law firm's MCP server, registered as legal in Claude Code, already holds its contract playbook. Lawyers want an "NDA check" routine: fixed review instructions plus the contract's file name as an argument, started when a lawyer chooses it by name. The firm does not want Claude starting the routine on its own during other work.Which way of adding the routine to the server best meets both needs?

Select one.

A Python Agent SDK agent in a CI job uses a vendor's remote MCP server, tracker, configured as an HTTP server with no headers. Its tools work in an engineer's interactive Claude Code session after signing in through /mcp. In CI, ClaudeSDKClient.get_mcp_status() reports tracker as needs-auth, and no tracker tool call appears in any transcript.What is the most likely root cause?

Select one.

A ticketing firm's MCP server runs over Streamable HTTP at a public HTTPS URL. It offers a search_tickets tool and exposes the escalation policy as a resource, which Claude Code users attach. A Python backend on the Messages API must let Claude search tickets and must send the current policy with every request. The server's code may not change.Which TWO changes best meet these needs?

Select two.

sources

  1. Model Context Protocol, "Versioning" and "Architecture": 2026-07-28 as the current revision; host, client and server, one client per server; JSON-RPC; capabilities on every request; server/discover; initialize in revisions up to 2025-11-25. Checked 2026-10-05.
  2. Model Context Protocol, "Server features", "Tools", "Resources" and "Prompts": model-, application- and user-controlled primitives; declared capabilities; isError results and protocol errors; slash commands. Checked 2026-10-05.
  3. Model Context Protocol, "Transports", "stdio" and "Streamable HTTP": the two standard transports; custom transports over Unix domain sockets or TCP reusing stdio framing; stdout only for MCP messages, logs on stderr; one endpoint, JSON or a request-scoped SSE stream; Origin validation against DNS rebinding; no protocol-level sessions. Checked 2026-10-05.
  4. Model Context Protocol, "Authorization": OAuth 2.1 for HTTP transports; stdio implementations retrieving credentials from the environment. Checked 2026-10-05.
  5. Model Context Protocol, "SDKs", "Build an MCP server" and "Connect to remote MCP servers", plus the Python SDK docs: SDK tiers; MCPServer (renamed from FastMCP in v2), @mcp.tool(), @mcp.resource(); McpServer.registerTool; logging to stderr; claude_desktop_config.json; custom connectors with resources and prompts. Checked 2026-10-05.
  6. Claude Code Docs, "Connect to external tools with MCP" (Agent SDK) and "Connect Claude Code to tools via MCP": mcp_servers and transport types; mcp__<server-name>__<tool-name>; .mcp.json read through the project setting source; claude mcp add; scopes; "type": "ws"; resources by @ mention; prompts as commands. Checked 2026-10-05.
  7. Claude Platform Docs, "MCP connector": beta header mcp-client-2025-11-20; only tool calls supported; publicly exposed HTTP servers, no local stdio; mcp_servers, mcp_toolset and authorization_token. Checked 2026-10-05.
  8. Claude Code Docs, "Tools reference" and "Custom tools": the built-in tools that list and read MCP resources; tools: [] removing every built-in tool. Checked 2026-10-05.
  9. IETF, RFC 3986, "Uniform Resource Identifier (URI): Generic Syntax": a URI is a compact sequence of characters that identifies an abstract or physical resource; the generic URI syntax, which starts with a scheme. Checked 2026-10-05.
  10. Shelfwise's stock_mcp code, its stdio launch and env names, the engineers' local registration and the feed_status resource are this course's additions to Shelfwise.