Deep-Dives / MCP
MCP
Building, testing, securing, and operating Model Context Protocol servers — the practical layer above mcp-architecture's conceptual introduction.
- Building MCP Servers in PracticeIdiomatic server construction beyond hello-world — FastMCP decorators, TypeScript Standard Schema, when to expose a capability as a tool vs a resource vs a prompt, and what to actually put in the median five-tool server.
- Designing MCP ToolsMCP tools are prompts as much as APIs — description phrasing changes selection, granularity changes token cost, and the search-then-fetch pattern beats "give the model the whole document" every time.
- Testing MCP ServersThe in-process pattern still wins, but both SDKs changed the door — and with no handshake left to test, what you assert instead is that every request stands alone.
- Streamable HTTP: the current MCP transportThe single-endpoint transport after the session header, the GET stream and resumability were all removed — what every POST must now carry, and what subscriptions/listen replaced.
- MCP Auth: the OAuth 2.1 ProfilePKCE mandatory, RFC 8707 resource indicators, Protected Resource Metadata for AS discovery, Client ID Metadata Documents beating Dynamic Client Registration — the MCP-shaped subset of OAuth, and why 39% of production servers ship with none of it.
- MCP Security Anti-PatternsThe six patterns the 2025-11-25 spec forbids by name — confused deputy, token passthrough, session hijacking, SSRF via discovery, javascript-URL injection, startup-command execution — with the trace signature and mechanical fix for each.
- Sampling & Elicitation via MRTRServer-initiated requests are gone: the server now returns its questions and the client retries the call carrying the answers — and the state it hands over in between is attacker-controlled input.
- Tool Poisoning: Prompt Injection via Tool DescriptionsTool descriptions are prompts your model reads — when they come from a downstream data source that also takes untrusted input, they become an indirect prompt injection surface (CVE-2025-54136, MCPTox).
- MCP Ops in ProductionPer-tool kill switches, argument-shape (not value) audit logs, tenant isolation from verified token claims (not request bodies), and rate-limits sized for agent traffic.
- MCP Registry & DistributionThe registry is still in preview: publishing with mcp-publisher and a server.json manifest, the six package types, the two 2026 changes that break existing publishers, and why the manifest cannot tell a host which protocol revision you speak.
- The 2026-07-28 RevisionRemoving the handshake deleted the one place negotiation, identity and server-initiated requests used to live — so all three reappeared on every single request, and a server that does not restate them is now malformed.
- Tasks & Long-Running WorkDeleting the session deleted every mechanism that carried work across a broken connection, so a task handle is the only thing left that survives a reconnect — Tasks is not the async option, it is the only option. Creation is server-directed, which means the server sets your retention, your poll rate and your retry story: `ttlMs` expiring under a human approval and a non-idempotent create are the two incidents, and both present as "tasks are flaky".
- Large Results & Pagination in MCPMCP paginates the catalog, not the call: opaque cursors cover only the four list methods, and `tools/call` has no cursor, size limit or chunking — so the same oversized result is spilled to a file, truncated at 40,000 characters or capped at ~150,000 depending on the host. The contract has to live in the tool's own arguments: an opaque cursor, a page ended by a token budget rather than a record count, an in-band `truncated` flag next to the remedy, and output a host can still grep after it spills it to disk.
- Large MCP Results in Code: Before, After & LibrariesOne pass-through tool, fixed step by step against 30 real pull requests: 187,521 tokens before, 5,379 after. Projection does 97% of the work; a token-budgeted page, a query-bound cursor, five contract tests and a middleware ceiling keep it there. Includes the three bugs the tests caught, a fastmcp proxy for servers you do not own, host hooks (and why the Claude Agent SDK hook fires after the size limit), and a measured evaluation of tokenizers, TOON, CSV and proxies.
- Enterprise-Managed AuthorizationThe first MCP auth mode where revoking an agent actually stops it: the enterprise IdP mints a per-server ID-JAG (RFC 8693 token exchange plus the RFC 7523 JWT bearer grant, `token_type: N_A`) and refuses the next exchange once policy says no. The whole benefit is the lifetime of the access token you mint after the exchange — issue hours and you have rebuilt the standing grant with extra ceremony. And it authorizes the connection, never the tool call.