How to Build an MCP Server: Production Guide (2026)

Q: What is the difference between MCP tools, resources, and prompts?

The Model Context Protocol defines three primitives, distinguished by who controls their invocation. Tools are actions the model itself decides to call (subject to user approval in most clients): each tool has a name, a natural-language description, and a JSON-Schema input, and the model chooses when to invoke it while pursuing a task — examples are creating a ticket, querying a database, or triggering a deployment. Resources are readable data addressed by a URI, such as a file, a log, or a database schema; they are application-controlled, meaning the client or host application decides which resources to attach to the model's context rather than the model fetching them autonomously. Prompts are reusable, parameterised prompt templates that are user-controlled — a person explicitly selects one, like a "summarise this incident" template, and the client fills in the arguments. In practice most servers begin with tools only, because actions are what agents most need, and add resources and prompts later when there is a clear case for exposing browsable data or standardised workflows. Understanding the control model matters because it determines your security posture: tools need the tightest design and authorization since the model drives them.

Q: Should my MCP server use stdio or Streamable HTTP transport?

Choose by who needs to reach the server. Stdio transport means the client application launches your server as a local subprocess and exchanges JSON-RPC messages over standard input and output. It is the right choice for local, single-user scenarios — developer tools, personal automations, anything that runs on the same machine as the client — because it requires zero network configuration and has no remote attack surface to secure. Streamable HTTP transport runs your server as an ordinary web service that clients reach over the network, and it becomes necessary the moment more than one user or more than one machine needs the server, which describes essentially every team or enterprise deployment. The critical implication of choosing HTTP is that your MCP server is now a web service with all the standard obligations: TLS, authentication (the MCP specification standardises OAuth 2.1 for this), per-user authorization, rate limiting, and monitoring. A common production shape in 2026 is a stateless HTTP MCP server deployed on serverless or container infrastructure, using the protocol's session-ID header for session continuity, scaled and operated exactly like any other API. Start with stdio for development regardless, then add the HTTP transport when you deploy.

Q: How do I write tool descriptions that AI models actually understand?

Treat the tool description as the only documentation the model will ever read, because it is. The model sees your tool's name, description, and JSON Schema — nothing else — and decides from those alone when to call it and how to fill in the arguments. The practices that measurably reduce misuse: give the tool a specific, verb-first name that states what it does (get_customer_orders, not data_query); write a description that says what the tool does, when to use it, and explicitly when not to use it, including pointing to the better alternative ("for aggregate statistics use get_order_summary instead"); constrain every argument as tightly as the schema allows, preferring enums over free strings, formats like date or uuid over bare text, and required fields kept minimal; and describe each parameter individually, with an example value where the format is not obvious. Also design the result with the model in mind: return the fields the model needs for its next step, not your database row. The reliable test is to show a colleague only the name, description, and schema and ask them to use the tool correctly on the first try — if a human cannot, the model will not either.

Q: How do I secure an MCP server in production?

Apply the same rigor you would to a public API, plus the agent-specific threats. First, authenticate every request: remote servers should implement the OAuth 2.1 flow the MCP specification defines, so the server knows which human user's authority each agent request carries, and tokens should be narrowly scoped and short-lived. Second — the step teams most often miss — enforce authorization server-side per user on every tool call. The model must never be the security boundary, because an agent whose context has been poisoned by prompt injection will attempt whatever its tools permit; if the server itself checks that this user may only read their own records, a hijacked agent is contained. Third, follow least privilege in tool design: expose the narrowest operations the use case needs, read-only where possible, and keep destructive operations behind separate tools with explicit confirmation semantics. Fourth, validate all inputs against the schema and sanitise anything that flows into queries or shell commands, since tool arguments are attacker-influenceable through the model. Finally, log every invocation with caller identity, arguments, and outcome so you have a forensic trail. Related risks like tool poisoning and the confused-deputy problem are a field of their own and worth studying before exposing anything sensitive.

Q: How much output should an MCP tool return?

As little as the agent needs for its next decision, because every byte a tool returns is injected into the model's context window, where it costs money, latency, and attention. A tool that dumps a 200 KB JSON response consumes on the order of 50,000 tokens of context in a single call — often more than the entire rest of the conversation — which both inflates the per-request cost and degrades the model's reasoning by burying the relevant facts in noise. The practical disciplines: cap response sizes at the server (truncate with an explicit "truncated, N more results" marker rather than silently); paginate list results and give the model a way to request the next page; return summaries or aggregates by default, with a separate drill-down tool for fetching full detail on a specific item; and strip fields the model has no use for, like internal IDs, audit columns, and verbose metadata. A good heuristic is that a tool result should fit in a few hundred tokens for routine calls, with a deliberate, documented exception for tools whose entire purpose is retrieving a document. Output discipline is one of the highest-leverage differences between a demo server and one that performs well under real agent workloads.

Q: How do I test an MCP server before pointing real agents at it?

Test at three levels, in order of increasing realism. First, the MCP Inspector — the official interactive development tool — connects to your server, exercises the protocol handshake, lists your tools, resources, and prompts, and lets you invoke them manually with arbitrary arguments; this catches schema errors, serialization problems, and transport misconfiguration in seconds. Second, unit-test your tool handlers as the ordinary functions they are: valid inputs, boundary values, malformed inputs, backend failures, and confirm that errors come back as structured, actionable messages rather than stack traces. Third — the level most teams skip and the one that matters most — run agent-in-the-loop evaluations: connect a real model to the server and give it realistic tasks, then check whether it selects the right tools, fills arguments correctly, and recovers from errors. This catches the failure class nothing else can: the model misunderstanding your tool because the name or description is ambiguous. Keep a small suite of these task-based evals and re-run them whenever you change a tool's name, description, or schema, because those changes alter model behaviour in ways ordinary tests are blind to. Only after all three levels pass should the server be registered with production clients.

Q: Should my MCP server just wrap my existing REST API?

Not one-to-one, and this is one of the most common design mistakes. Your REST API is shaped for developers who read documentation, hold state in their heads, and compose calls with code; an agent instead reasons in natural language over tool descriptions and pays a context-window cost for every call and every result. Mirroring your API means exposing dozens of granular CRUD endpoints, which forces the model to plan multi-step call sequences it will frequently get wrong, and floods its context with intermediate results. The better approach is to design task-shaped tools around what the agent is actually trying to accomplish: a single resolve_customer_issue or get_account_health tool that internally orchestrates five REST calls beats exposing those five endpoints directly, both in reliability and in token cost. Keep the tool count modest — servers with a handful of well-designed, well-described tools consistently outperform servers with fifty thin wrappers, because tool selection is itself a reasoning burden that grows with the menu. Your REST API remains the backing implementation the MCP server calls internally; the MCP layer is a purpose-built facade for a different kind of consumer. Think of it as designing a new interface for a new audience, not translating an old one.

Q: What goes into the audit logging for an MCP server?

Log every tool invocation as a structured event carrying at minimum: the authenticated caller identity (the human user whose authority the agent carries, plus the client application), the tool name, the full arguments as received, the timestamp, the latency, the outcome (success, business error, or system error), and a compact representation of what was returned or changed. This matters more for MCP servers than for ordinary APIs for two reasons. First, agents generate call patterns humans never would — rapid retry loops, unusual argument combinations, exploratory sequences — and the invocation log is the only way to understand, debug, and improve how models actually use your tools; it directly feeds schema and description refinements. Second, it is your forensic record: when an agent does something surprising or a prompt-injection incident is suspected, the question "which user's agent called which tool with which arguments, and what did it get back" must be answerable in minutes, and nothing else in your stack can answer it. Route these events into your existing observability pipeline, alert on anomalies like sudden spikes in a destructive tool's usage, and retain them under the same policy as other security-relevant logs. Skipping this is the single most regretted omission among teams running agent infrastructure at scale.

Satyam Kumar

返回博客

ai-architecture

How to Build an MCP Server: Tools, Resources, and Production Architecture

By Satyam KumarJuly 2, 20267 min read

mcp server model context protocol build mcp server mcp tools mcp resources mcp python sdk mcp typescript sdk streamable http stdio transport ai agent integration tool calling json-rpc oauth 2.1 agent security ai architecture patterns 2026

How to Build an MCP Server: Tools, Resources, and Production Architecture

Frequently Asked Questions

分享这篇文章

Twitter LinkedIn WhatsApp

Satyam Kumar

Founder & AI Architect, AppScale LLP

人工智能和云架构师。帮助团队构建可扩展到数百万的系统。

LinkedIn GitHub

How to Build an MCP Server: Tools, Resources, and Production Architecture

Frequently Asked Questions

分享这篇文章

Comments

Leave a comment