jonas.splinter
Search
Blog

Tips and tricks for building your own small, public MCP server

Practical lessons from building two public, read-only MCP servers: the smallest protocol that works, the mistakes that are easy to make, and what helped people find them.

I have now built two public, read-only MCP servers: one for Automate & Tweak (opens in a new tab), a directory of about 1,400 AI tools, and one for this site at jsplinter.nl/mcp. Both were built together with Claude Code. These are the lessons, so you can build a small one for your own site and skip my mistakes.

What an MCP server for a website is

The Model Context Protocol lets an AI assistant such as Claude, ChatGPT or Cursor use your data directly. For a website, the server is one HTTP address. The assistant sends it JSON-RPC 2.0 messages with POST, and the server offers a set of "tools" that the model can call: search the catalogue, fetch one item, list the categories. Mine are read-only and public: no login, no keys. If you know HTTP and JSON, you already know most of what you need for MCP.

The smallest server that works

The transport is called Streamable HTTP. It allows streaming and sessions, but you do not need either. A stateless server is enough: one POST comes in, one JSON answer goes out. Four methods cover a read-only server:

  • initialize: the handshake. You return your protocol version, your capabilities (tools), your server name and optional instructions for the model.
  • ping: return an empty result.
  • tools/list: return your tools, each with a name, description and JSON Schema for its arguments.
  • tools/call: run one tool and return the result.

A message without an id is a notification, such as the notifications/initialized that clients send after the handshake. Answer it with HTTP 202 and an empty body. Batches of messages were removed from the specification in version 2025-06-18, so you can skip them.

For version negotiation, look at the protocolVersion the client sends. If you support it, echo it back. If not, answer with the newest version you do support and let the client decide.

You can try the handshake yourself against this site's server:

curl -s https://jsplinter.nl/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"test","version":"1"}}}'

You do not need an MCP library for this. The jsplinter.nl server is one plain PHP file with the protocol code plus the tool functions. The Automate & Tweak server is about 350 lines of protocol code inside a Laravel app.

Things that are easy to get wrong

Empty objects in PHP

In PHP an empty array encodes as [], but the protocol wants {} in a few places: the result of ping, and the properties of a tool that takes no arguments. Use an empty object:

json_encode(['result' => []]);              // {"result":[]}  wrong
json_encode(['result' => new stdClass()]);  // {"result":{}}  right

'inputSchema' => ['type' => 'object', 'properties' => new stdClass()],

Return every result twice

structuredContent must be a JSON object, so wrap a list in one: {"updates": [...]}. Next to it, return a short readable text with one line per item and the canonical URL of each item. The specification also recommends putting the serialised JSON in a text block for clients that ignore structured content, so I add it as a second text block.

Errors the model can fix

If the model sends an unknown slug, a wrong date or a filter value that does not exist, do not answer with a JSON-RPC error. Return a normal tool result with isError: true and a sentence that tells the model what to do next:

{"jsonrpc":"2.0","id":7,"result":{
  "content":[{"type":"text",
    "text":"Unknown tag 'x'. Use list_tags for valid keys."}],
  "isError":true}}

Keep JSON-RPC error codes for real protocol faults, such as a method that does not exist or a body that is not valid JSON.

The HTTP layer

  • Never answer 401 on the endpoint, and let the OAuth discovery addresses (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server and /register) return a plain 404. A 401 makes a client start a login flow, and clients do probe those addresses.
  • Never redirect the POST: no trailing-slash redirect, no www redirect. Many clients turn a redirected POST into a GET. On jsplinter.nl the address /mcp needed its own web server rule for exactly this reason.
  • Answer GET with 405 Method Not Allowed, so clients do not wait for an event stream. A trick I saw on levels.io: if the GET comes from a browser (Accept: text/html), show a human explainer page at the same address. That gives you one address to share. Open /mcp in a browser to see it.
  • Answer OPTIONS and send Access-Control-Allow-Origin: * if browser-based clients should work. The specification asks servers to check the Origin header, mainly to protect servers that run locally. For public, read-only data without a login, an Origin allow-list protects nothing, so I allow all origins.
  • Whatever sits in front of your app, such as caching or bot protection, must let non-browser clients POST JSON. No JavaScript challenge and no page cache on that address.

Designing the tools

Five to eight tools is plenty for a small site. One tool per kind of public page works well: a list and a detail tool for projects, a search and a detail tool for updates, a list of tags. Name them verb_noun, such as search_updates and get_project.

Write each description for the model, not for yourself. Say what comes back and which tool to call next, and say where valid filter values come from ("use list_tags for valid keys"). Give every tool a human title and mark it read-only with the annotations readOnlyHint: true and destructiveHint: false. Some directories require this.

The instructions field you send with initialize is a good place for a suggested order of calls and for a rule like "always link to the returned URL".

The biggest lesson came from Automate & Tweak. Models do not send keywords. They send the user's sentence: "best free AI tools for video editing", or "chatgpt alternative". A search that requires every word to match returns nothing for that. What works is matching any word, ranking by how many words match, stripping filler words, and saying in the result what you did, so the model can judge the answer. That took two rounds of fixes there. On jsplinter.nl I built the search that way from the start.

One more idea from levels.io: a tool that lists your other MCP servers and says when to suggest them. This site has one, list_mcp_servers, which points to the Automate & Tweak server.

Privacy, limits and monitoring

Both servers allow 60 requests a minute per client network and answer 429 with a Retry-After header when that is exceeded.

I count calls per tool per day and nothing else: no IP addresses, no questions. Most traffic is not people anyway. In its first eleven days, the Automate & Tweak server received about 13,000 requests, and only about 2.4% of them were real tool calls. The rest were handshakes from registry crawlers, uptime monitors and probes, many with junk arguments. So the share of errors looks bad without being a bug.

Test from the outside with a script that covers every method, every tool, the error paths and a check that no draft or private content leaks. Add one check that deliberately expects the wrong thing, to prove the script really catches faults. The jsplinter.nl script has about fifty checks. Then set up an uptime check that makes a real tools/call, not just a ping. Automate & Tweak did not have one at first.

Getting found

The one step with a visible effect for Automate & Tweak was publishing in the official MCP Registry. Crawlers arrived within a day, and another directory picked up the server by itself. The name is the reverse-DNS form of your domain, for example nl.jsplinter/jsplinter. You prove that you own the domain with a small key file on your site. Entries cannot be edited, so a change means publishing a new version.

For Automate & Tweak I also built a server card, an AI catalogue file and explainer pages in several languages. I saw no measurable effect from any of them. My advice is to skip them at first.

An explainer page for people does matter. Put the address on it with a copy button, setup steps per assistant, example questions, and a note on fair use and privacy. The setup steps differ in small ways: Cursor uses mcpServers with "url", VS Code uses "servers" with "type": "http", and Gemini CLI uses "httpUrl".

What I do not know yet

Neither server has yet been observed with large numbers of real assistant users, so I cannot tell you how people use them in practice. The setup steps per assistant come from the vendors' documentation, not from testing every client myself. And I have not measured whether models actually follow the instructions text.

Frequently asked questions

Do I need streaming or sessions for a small MCP server?

No. A stateless server is enough: one POST comes in, one JSON answer goes out. Four methods cover a read-only server: initialize, ping, tools/list and tools/call.

How many tools should a small site offer?

Five to eight is plenty. One tool per kind of public page works well, with each description written for the model, not for yourself.

How do people find a public MCP server?

For Automate & Tweak, publishing in the official MCP Registry was the one step with a visible effect. An explainer page with the address, setup steps per assistant and example questions helps people too.

What to do first

  1. Pick three to five things your site already publishes and write one read-only tool for each.
  2. Build the four methods as a single stateless POST endpoint, and test them with curl.
  3. Check the HTTP layer: no redirects, no 401, 405 on GET, nothing in front that blocks a JSON POST.
  4. Write an outside test script, including one check that should fail, and an uptime check that calls a tool.
  5. Write a short explainer page, then publish in the official MCP Registry.

If you want to see how this looks in practice, try this site's own server or read the Automate & Tweak explainer (opens in a new tab), and connect your assistant to either one to see a small public API at work.

Related updates

Short notes on the same topics