All posts

How to build a custom MCP server in 2026 (2026-07-28 spec ready)

A step-by-step guide to building a custom MCP server on the 2026-07-28 spec: tool design first, stateless core with handles, Mcp-Method and Mcp-Name, multi round-trip input, OAuth, and the tests that prove it.


Most tutorials on building an MCP server were written for the 2025-11-25 revision. They open a session, run the initialize handshake, keep state in memory, and call it done. On the 2026-07-28 spec, that code still answers old clients, but it is not what a new server should look like.

This guide is for a team that wants a custom MCP server on top of its own product, built for the current spec from day one. It follows the order I use in practice: design the tools first, then the stateless core, then the transport, then authorization, then the tests. Code comes late on purpose.

What a custom MCP server actually is

An MCP server exposes your product to an AI client (Claude, ChatGPT, Cursor and others) as tools, resources and prompts. The client's model decides when to call a tool, with which arguments, and what to do with the result.

"Custom" means the server is designed around what your users ask an assistant to do, not generated from your REST API. A generated wrapper exposes every endpoint as a tool. A designed server exposes a handful of tasks the model can pick between without guessing. That difference decides whether the assistant uses your product correctly or fumbles it, and it is covered in detail in REST wrapper or agent-designed MCP server.

Step 1. Design the tools before writing code

Start from the sentences your users will type, not from your database schema. For each sentence, write down which tools the model has to call, in which order, and what each one returns.

Three rules hold up in production:

  • One tool, one job. A tool named after a task (create_invoice, list_overdue_invoices) beats a generic query tool with a mode parameter.
  • Descriptions are written for the model. Say when to use the tool, when not to, and what the arguments mean in business terms. See writing MCP tool descriptions.
  • Keep the surface small. Every extra tool is one more option the model can pick by mistake. How many is too many is covered in how many tools an MCP server should expose.

Mark write tools clearly, and separate them from read tools. That split is what you will later hang permissions, confirmations and rate limits on.

The 2026-07-28 revision loosens inputSchema and outputSchema to accept any JSON Schema 2020-12 keyword, and structuredContent can be any JSON value. Use that to describe arguments precisely rather than accepting free text and parsing it yourself.

Step 2. Build a stateless core

Protocol-level sessions are gone in 2026-07-28. There is no Mcp-Session-Id header anymore, and the initialize handshake is removed. Every request carries its protocol version and client capabilities in _meta, under io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities.

For a new server, this is good news: you never have to unlearn session state. Each handler receives everything it needs in the request, rebuilds the user context from the token, does its work, and returns.

When a workflow genuinely spans several calls (a draft built step by step, a paginated export), the spec's answer is a handle. Your server mints an opaque identifier, returns it from one tool, and accepts it as an ordinary argument on the next. The state behind it lives in your storage, not in a process. The pattern is explained step by step in Stateless MCP: replacing Mcp-Session-Id with handles.

Also implement server/discover. The spec makes it mandatory: it is how a client learns which protocol versions, capabilities and identity your server advertises.

Step 3. Handle the transport correctly

For a remote server, use Streamable HTTP. The older HTTP+SSE transport is classified as deprecated.

On every POST, the 2026-07-28 spec requires two headers, Mcp-Method and Mcp-Name, which mirror the JSON-RPC method and the name being called. They let a gateway route, rate limit and log per tool without opening the body.

The server side has one duty here: compare the headers with the body and reject any mismatch. A header is a declaration, not a proof. If your policy trusts it blindly, a request can advertise a harmless read tool and call a write tool. Details in Mcp-Method and Mcp-Name: routing MCP traffic without reading the body.

Three more transport points from the changelog:

  • Results returned by tools/list and the other list endpoints must carry ttlMs and cacheScope. Pick a TTL that matches how often your tool set really changes.
  • Return tools in a deterministic order, which the spec recommends to help client caching.
  • SSE resumability is removed. If a response stream breaks, the client re-issues the request with a new ID, so make write tools safe to retry.

Step 4. Ask for missing input the 2026-07-28 way

A server that needs more information mid-call (a confirmation, a missing field) no longer sends its own request to the client. Under the Multi Round-Trip Requests pattern, the tool returns an InputRequiredResult with resultType: "input_required" and the list of what it needs. The client retries the original request with inputResponses.

Every result now carries a resultType, "complete" for ordinary ones. Build that in from the first handler.

Do not add Roots, Sampling or Logging to a new server. All three are deprecated: pass paths through tool parameters or configuration, call your model provider directly, and log to stderr or OpenTelemetry. Long-running jobs moved to the io.modelcontextprotocol/tasks extension, covered in long-running work with MCP Tasks.

Step 5. Add authorization from the start

If your server touches user data, it needs OAuth, and retrofitting it later is the most expensive change you can make. The 2026-07-28 revision tightened several points:

  • Authorization servers should send the iss parameter (RFC 9207), and clients must check it before redeeming the code.
  • Client credentials are bound to the authorization server that issued them.
  • Dynamic Client Registration is deprecated in favour of Client ID Metadata Documents, and stays available for backwards compatibility.

On the server side, the practical work is publishing correct protected resource metadata, validating tokens and their audience on every request, and checking per-tool permissions, write tools first. The full chain is in OAuth for MCP servers in 2026.

Step 6. Test like a client would

Unit tests are not enough. Before calling the server done:

  • Run it in the MCP Inspector and call every tool by hand.
  • Run two instances behind a plain load balancer with no sticky sessions, and play a multi-step scenario while killing one. If it survives, the core is really stateless.
  • Send requests whose Mcp-Name does not match the body, and check they are rejected and logged.
  • Use the error codes from the current spec: resource not found is -32602, no longer -32002.
  • Then try it in a real client with real sentences from Step 1, and read which tools the model picked.

Before going live, go through the security gaps we see in production MCP servers.

When to have it built

A good developer on your team can build this. The time goes into the parts nobody on the team has met yet: tool design for a model with no screen, the OAuth chain, and conformance with a revision that is still recent.

Building in-house makes sense if the server becomes a core asset you evolve every month. Having it built makes sense if that time is worth more on your product, or if you would rather not learn the protocol at your own expense. What drives the cost either way is laid out in what an MCP server really costs.

FAQ

Can I start from the official SDK?

Yes, and you should. The SDKs handle the protocol plumbing. What they do not do for you is tool design, state handling and authorization, which is where most of the work is.

Does a server built for 2026-07-28 still work with older clients?

The spec lets clients fall back to the old handshake against an older server, and some SDKs can serve both revisions from one endpoint. Check what your SDK supports before promising it.

Should I expose my whole API?

No. Expose the tasks your users ask for. A smaller, well-described tool set is easier for the model to use correctly.

Local (stdio) or remote (HTTP)?

Local suits a developer tool running on one machine. As soon as the server serves your customers with their own accounts, it is remote, over Streamable HTTP, with OAuth.

Want it built properly the first time

I design and build production MCP servers on the 2026-07-28 spec: tools designed for an agent, stateless core, OAuth, deployment and observability. The offers and their published prices are on the MCP servers page. The first written opinion is free.

Have a project? Tell me about your MCP server →

Related reading

Official sources

Got an MCP server to audit?

Five minutes to describe it. I reply within one business day with a first written diagnosis, free of charge.

Get my MCP server audited
How to build a custom MCP server in 2026 (2026-07-28 spec ready)