People in Georgia (the country in the Caucasus) ask chatbots things like "is this snake in my yard dangerous?". The answers are often generic, sometimes wrong, and never point to a source.

I run Reptiles.ge, an atlas of the animals of Georgia: snakes, lizards, turtles and amphibians in depth, plus birds, mammals, spiders, scorpions and insects. It has 145 published species profiles in four languages (Georgian, English, Russian, Turkish). So I gave it an MCP server, and now Claude, ChatGPT and other assistants can read the atlas directly and link the page they used.

The server is live at https://api.reptiles.ge/v1/mcp. No key, read-only. Here is how it is built, and why I skipped the official SDK.

The setup it plugs into

The site already had a JSON API: a Hono app on a Cloudflare Worker, reading from a D1 database (SQLite at the edge). Species profiles, news, field records and photo credits all live in D1. The website itself is a Next.js app that reads the same API on the server.

So the MCP server did not need its own data layer. It is one more route on the same Worker, reading the same tables the website renders. Whatever an assistant reads is exactly what a visitor sees.

Why no SDK

The official TypeScript SDK is good, but it brings session handling, transports and an event stream that a read-only catalogue does not need. On Workers I also wanted every request to be independent: no Durable Object, no in-memory session, nothing to clean up.

The Streamable HTTP transport allows that. A server may answer a JSON-RPC POST with plain JSON and never open a stream. So the whole server is:

  • POST /v1/mcp takes one JSON-RPC message and returns one JSON response.
  • A notification (no id) gets 202 Accepted with an empty body.
  • GET /v1/mcp answers 405, because there is no event stream to open.

The route is short enough to show in full:

export const mcp = new Hono<ApiEnv>() .post( "/", rateLimitMcp, validate("header", mcpProtocolHeader), validate("json", mcpMessage), async (c) => { const version = c.req.valid("header")["mcp-protocol-version"]; if (version !== undefined && !SUPPORTED_VERSIONS.includes(version)) { throw new ApiError(400, "invalid_request", "Unsupported MCP version"); } c.header("Cache-Control", "no-store"); const answer = await answerMcp(c.env.DB, c.req.valid("json")); return answer ? c.json(answer, 200) : c.body(null, 202); }, ) .get("/", (c) => { c.header("Allow", "POST"); throw new ApiError(405, "method_not_allowed", "POST only, no event stream"); }); 

The handler, the Zod schemas for the messages, the four tools and the rate limiter come to about 500 lines together.

Four methods are enough

A tools-only server has to answer four JSON-RPC methods:

switch (message.method) { case "initialize": return result(id, { capabilities: { tools: {} }, instructions: INSTRUCTIONS, protocolVersion: negotiatedProtocolVersion(message.params?.protocolVersion), serverInfo: { name: "reptiles-ge", version: "1.0.0", websiteUrl: "https://reptiles.ge" }, }); case "ping": return result(id, {}); case "tools/list": return result(id, { tools: MCP_TOOLS.map(toToolDescription) }); case "tools/call": return callTool(db, id, message.params); default: return failure(id, -32601, "Method not found"); } 

Version negotiation is one line: if the client asks for a version I support (2025-11-25, 2025-06-18 or 2025-03-26), I echo it, otherwise I offer the newest. Every tool is marked readOnlyHint: true and idempotentHint: true, so clients can call it without asking the user for confirmation each time.

The tools

Tool What it returns
search_species Short cards: name in any of the four languages, group, region, habitat, danger level
get_species The full profile: identification, range in Georgia, danger to people, lookalikes, sources
search_news News articles, newest first
get_news One article with its sections and sources

Every result carries the URL of the public page in the requested language. That was the point of the whole exercise: the assistant should cite the atlas, not paraphrase it into the void.

You can try it with curl:

curl -s https://api.reptiles.ge/v1/mcp \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_species","arguments":{"query":"Levantine viper","locale":"en"}}}' 

The structuredContent of the answer:

{ "locale": "en", "results": [ { "id": "macrovipera-lebetina", "commonName": "Levantine viper", "scientificName": "Macrovipera lebetinus", "group": "snake", "danger": "High", "location": "Eastern Georgia", "url": "https://reptiles.ge/en/snakes/macrovipera-lebetina" } ], "total": 1 } 

The same tool result also goes out as a JSON string in content, for clients that do not read structuredContent yet.

Instructions do real work

The initialize response has an instructions field, and it is the only place to tell a model how to treat your data. Mine says, among other things:

  • Answer in the user's language with the matching locale. Georgian is the canonical text.
  • Lists hold published atlas profiles only, not the complete fauna of Georgia. An empty field means the atlas has published nothing there, not "none". Do not fill it in.
  • Cite the URL of the page you used, and the photographer when you show a photo.
  • The danger level is an educational label, not medical advice. For a snake bite in Georgia, tell the user to call 112.

The second rule matters more than it looks. Without it, a model reads a missing conservation status as "not threatened" and states it confidently.

Errors: protocol vs tool

MCP has two kinds of failure, and mixing them up confuses clients:

  • Bad input (an unknown tool, arguments that fail the Zod schema) is a JSON-RPC error, -32602 Invalid params, with the Zod issues in data.
  • A valid call that finds nothing (a species id that does not exist) is a normal result with isError: true and a text message. The model can read it and try a different search.

get_species also resolves former slugs and the scientific name written as a slug. A model that asks for vipera-ammodytes or macrovipera-lebetinus still lands on the right profile.

Rate limiting without a key

The server needs no API key, so the limit is per IP: 60 requests a minute through the Workers rate-limiting binding, answered with 429 beyond that. Responses are no-store, so a client never gets a stale answer from a cache in between.

Connecting it

In Claude: Settings → Connectors → Add custom connector, then paste https://api.reptiles.ge/v1/mcp. Other clients that support remote MCP servers over Streamable HTTP take the same address.

Then ask something like "we're hiking near Vashlovani tomorrow, which snakes should we watch for?" and watch it call search_species and get_species before it answers.

Links

If you build a small read-only MCP server for your own data, I'd skip the SDK at first. Four methods, one POST route, and you can read every byte that goes over the wire.