How to build an MCP server
The protocol part is easy — the official SDKs get you a working server in an afternoon. What separates a great MCP server from a tool dump is design: which jobs it serves, how honest its schemas are, and whether an agent can trust it. Here's the whole path, in seven steps.
The best MCP servers aren't API wrappers — they expose jobs, not endpoints. List the 5–10 things an agent should be able to accomplish, then design one tool per job. Twelve sharp tools beat eighty auto-generated ones: every extra tool costs context tokens and adds a way for the model to pick wrong. (This is the core argument of our manifesto on building the best MCP.)
stdio — a local process the client launches (npx -y your-mcp). Right for tools that need the user's machine: files, local git, databases on localhost.
Streamable HTTP — a remote URL you host. Right for SaaS-backed tools: no install, you control the runtime and can update server-side, and OAuth fits naturally. Remote is winning for anything with an account behind it; SSE is legacy — new servers should use Streamable HTTP.
Use the official SDKs — @modelcontextprotocol/sdk (TypeScript) or mcp (Python). A minimal server is ~30 lines: create the server, register tools, bind the transport. Don't hand-roll the protocol; the SDKs handle the JSON-RPC framing, capabilities negotiation, and session plumbing.
Each tool needs a name the model can pick correctly, a description that says when to use it (and when not to), and a typed input schema with real constraints. Mark behavior with annotations — readOnlyHint, destructiveHint — and mean them: agents and gateways increasingly make policy decisions from these hints. Return structured, compact results; a tool that dumps 50KB of JSON into context is a bug.
Local servers: take credentials via environment variables, never CLI args (they leak into process lists). Remote servers: OAuth with explicit, minimal scopes. Never log secrets, and design so a leaked token has the smallest possible blast radius — the six risks on our MCP security guide are exactly what reviewers (and we) check for.
npx @modelcontextprotocol/inspector gives you an interactive client: verify the handshake, eyeball every tool's schema, and call each tool with real inputs. Then test the failure paths — bad auth, missing params, upstream timeouts — because the model will hit them, and a good error message is how it recovers.
Publish to the official MCP registry (mcp-publisher CLI), list it on the directories, and add an llms.txt to your docs. Submit it to MCPExplorer — we'll run the live handshake, verify the real tool surface, label each tool's risk, and give it a page (and a badge) that shows agents and humans exactly what it does.
What language should I build an MCP server in?
TypeScript and Python have the official, best-maintained SDKs (@modelcontextprotocol/sdk and mcp). Pick whichever your team ships fastest; the protocol is identical. Community SDKs exist for Go, Rust, Java, and C#.
Should my MCP server be local (stdio) or remote (Streamable HTTP)?
Local (stdio) if the tools need the user's machine — files, local processes, localhost databases. Remote (Streamable HTTP) if the tools front a SaaS API — no install for users, natural OAuth, and you can update server-side. New remote servers should use Streamable HTTP, not the legacy SSE transport.
How many tools should an MCP server expose?
As few as cover the real jobs — usually 5–15. Every tool's schema is loaded into the agent's context, so an 80-tool server taxes every request and gives the model more ways to choose wrong. Design one tool per job an agent actually does, not one per API endpoint.
How long does it take to build an MCP server?
A working prototype with the official SDK is an afternoon. Production quality — honest schemas, risk annotations, auth done right, failure-path handling, tests — is more like a week. The protocol is the easy part; tool design is the real work.
How do I get my MCP server listed and trusted?
Publish to the official MCP registry, then submit it to directories. On MCPExplorer, submitted servers go through a live tools/list handshake (local servers in a hardened sandbox), get per-tool risk labels and an explainable trust score, and earn an embeddable 'featured/listed' badge.
Submit it to the index — we'll verify the real tool surface with a live handshake, label every tool's risk, and give it a page agents can trust.
Submit your MCP server