Research MCP Server
Personal research on design patterns for genuinely useful MCP servers - beyond hello-world, with auth, pagination, and error handling transparent to the agent.
Almost every MCP example stops at the toy. The engineering lives in production.
The Model Context Protocol is an open protocol that lets AI agents connect to external tools and data through servers that expose tools, resources, and prompts - over stdio or HTTP. The idea is great, but most examples stop at a tool that adds two numbers and never touch what actually matters.
What matters is precisely the boring part: authentication and authorization for remote servers, pagination of large result sets so the agent isn't flooded, and transparent, actionable errors instead of opaque stack traces. That's where the real engineering lives - and it's what almost nobody documents.
A personal project: mapping the patterns that separate a toy MCP server from a production one.
- - Authentication and authorization: OAuth 2.1 with PKCE for remote servers, tokens scoped per tool, and authorization checks before any sensitive action - no single credential for everything.
- - Token-aware pagination: cursors on list operations, with the limit described in the schema itself so the model knows the response is paginated.
- - Transparent error handling: structured JSON-RPC errors the agent can interpret and recover from.
- - Tool and resource design: typed contracts with Zod, idempotency where it makes sense, and token-budget-aware responses.
- - Claude Agent SDK as the bench: I use the SDK as a harness to exercise the server with a real agent and see where the patterns break in practice.
Leave the hello-world behind and treat the server like a real API.
Most examples stop at a tool that adds two numbers. The real engineering starts when the server exposes production data and needs a contract, limits, and versioning.
Design tools around the agent's token budget.
A tool schema is a fixed cost - it loads every time the tool is available. Short, unambiguous names, lean descriptions, and responses that fit the window instead of dumping everything at once.
Paginate large result sets so the model isn't flooded.
List operations use cursors and limits, with the behavior explicit in the schema. The agent asks for the next page when it needs it - the server doesn't try to hand back ten thousand rows in a single response.
Fail in a way the model can actually recover from.
Structured errors, with a code and an actionable message, instead of an opaque stack trace. The agent reads the error, understands what to do (refresh the token, fix an argument, retry) and moves on - without stalling the task.
Instead of one more toy tool, it's turning into an honest set of patterns for MCP servers that could take a real user - with the rough edges still showing.
- - The patterns are being documented as they showed up, not as closed theory - each one came out of a concrete failure while exercising the server with the agent.
- - OAuth with per-tool scope is already mapped; the trade-off between service-account and on-behalf-of is still open.
- - Cursor pagination clearly cut down window blowups on large listings; standardizing the cursor format across tools is still pending.
- - It stays personal, ongoing research, not a shipped product - the goal is the playbook, not the server itself.