OpenSearch MCP server is the textbook stateless design. Some MCP servers cannot be that, and the contrast is the most useful thing you can learn about MCP.

What the OpenSearch MCP server actually exposes

The repository at github.com/opensearch-project/opensearch-mcp-server-py is a Python project published by the OpenSearch project itself. You install it from PyPI, point it at a cluster, and it speaks MCP over stdio or over a streaming transport (SSE or Streamable HTTP). The default-on tool surface is small and shaped like the OpenSearch REST API.

Every one of those tools is independent of the others. Calling SearchIndexTool does not put the server into a mode that subsequent calls have to respect. The hits come back keyed by document _id, and the agent passes those ids forward into ExplainTool, GetShardsTool, another search, or whatever else makes sense. Pagination is another self-contained call: same query body, different from and size, or a search_after cursor.

What stateless looks like in code

Here is the shape of the search tool, paraphrased to the part that matters. There is no instance variable on the server that survives past the return statement. The query body is fully self-describing, and the response is just a projection of the upstream result.

That shape is what most readers expect when they hear "MCP server." Tools as named functions. Each tool maps to one upstream call. Identifiers in the response that survive across calls. Order of calls is irrelevant beyond what the agent decides. For OpenSearch the shape is correct, and the project ships exactly it.

The shape on the wire is the same. The shape of the data is not.

JSON-RPC framing is identical for any MCP server. Stateless or stateful, the bytes between the host and the server look the same. What differs is what the server does inside the call, and what the return value lets the next call do.

One round trip per tool call. The reply carries _ids. The agent picks one and uses it later. Nothing on the server persists. Now compare against an MCP that has no stable id to return, because there is no database underneath, just a UI.

Two round trips, deliberately. The first one types into the sidebar, parses the visible result buttons out of the accessibility tree, and returns them with 0-based indices. It does not close the search field. The second tool call, whatsapp_open_chat, takes one of those indices and clicks the button at that ordinal position in the still-open UI. The state lives in WhatsApp, not in the MCP server, but the MCP server is responsible for not disturbing it between calls.

The two-tool handshake, in source

The relevant code is in Sources/WhatsAppMCP/main.swift. The first half is the search tool. The comment at the bottom of the function is load-bearing: it is the contract the next call depends on.

The follow-up tool is right below it. The argument it accepts is a single integer. The tool description, declared further down in the file at line 1050, instructs the agent to call whatsapp_search first and then pass through the index. The implementation re-walks the AX tree, collects the same result buttons, and clicks the one at that ordinal.

That ordinal is the entire identifier. There is no document id, no phone number used as a key, no stable handle the way OpenSearch hands you a _id. The agent has only the position of the result in the live UI, and the position only stays valid as long as the search is open and nobody else moves around in WhatsApp. That is the cost of not having a queryable data store underneath.

The full tool surfaces, side by side

OpenSearch's default-on tools cover index management, search, and a few diagnostic primitives. WhatsApp MCP's eleven tools cover a much narrower domain (one app on one OS) but two of them are deliberately stateful in a way no OpenSearch tool is.

Three tools form the search-and-open-a-chat handshake: whatsapp_search opens the search UI and returns indexed results, whatsapp_scroll_search extends the same open UI with more results, and whatsapp_open_chat consumes one of the indices to actually navigate. Neither OpenSearch's SearchIndexTool nor MsearchTool need a partner tool to land a result. They return enough by themselves.

Per-feature breakdown

What changes between the two designs, and why each change is forced by the data source rather than by taste.

Which shape should you reach for

The decision is almost entirely a function of what is on the other side of your MCP server, not of what the protocol allows.

1. A queryable store with stable record ids. OpenSearch, Elasticsearch, Postgres-with-an-API, and most modern SaaS (Stripe, Linear, Notion, Slack, GitHub) sit here. Every record has an id you can hand back to the agent, and the upstream API accepts arbitrary filters. Build the OpenSearch shape: small tools, one HTTP call each, identifiers in the return that the agent carries forward. There is no reason to keep state on the server, and adding state will only create bugs.
2. A surface with no public id and no API for individual users. WhatsApp consumer accounts, iMessage, Apple Notes, Things, Bear, and most native macOS apps sit here. The only handle on a record is its position in the UI right now. Build the WhatsApp shape: tools that explicitly say what UI state they leave open, return objects with positional indices, follow-up tools that consume those indices, and verification tools the agent can call to re-anchor before any write. State is unavoidable. The honest move is to admit it in the tool descriptions instead of pretending the server is stateless.
3. The mixed case, where the data is queryable but writes go through a UI. You can read messages over an API but only send via the desktop app, for example. Split the surface into two namespaces: stateless read tools that pass through the API, stateful write tools that drive the UI. Do not pretend the writes are stateless. The agent will assume any write tool is safe to call concurrently, and that assumption breaks the moment your write path is a click.

What WhatsApp MCP would have to look like if WhatsApp shipped an OpenSearch

For the sake of the comparison, imagine WhatsApp consumer accounts exposed a per-user REST API that let you query messages and contacts by stable id, the way OpenSearch lets you query indices. The MCP server for it would collapse. The eleven tools in main.swift would shrink to about four: search_chats, read_messages, send_message, and a generic API passthrough. The two-call search-and-open handshake would disappear, because every chat would have a stable phone-number-keyed handle and send_message could just take that handle as an argument. Pagination would move to the API and become stateless. The whole accessibility-tree traversal would become dead code.

That is exactly what the OpenSearch MCP server gets to be. The data store does the work of giving every record a name. The MCP server's job is just to expose those names to the agent in a shape MCP hosts know how to consume. Anyone writing an MCP server against a real database (OpenSearch, Postgres, MongoDB, SingleStore, ClickHouse) is downstream of that gift. Anyone writing an MCP server against a desktop app is not.

How both servers handle pagination

Pagination is the cleanest place to see the design split. In OpenSearch MCP server, the agent decides how to paginate by choosing what to put in the request body. The classic pair from and size works for shallow pages. For deep pages, search_after gives the agent a sort cursor it can carry forward. Either way, the next page is a fresh, fully-formed call. The server has no opinion on what page you are on.

In WhatsApp MCP, the equivalent is whatsapp_scroll_search (defined at line 1059 in the same file). Because there is no offset parameter exposed by the WhatsApp app, the tool literally sends scroll-wheel events at the midpoint of the visible result buttons, sleeps briefly so the app can lazy-load, and then re-walks the AX tree to return the now-larger set. Calling it after the search has been closed does nothing useful. Calling it before the search has been opened returns an error. There is no stateless variant of this in the WhatsApp MCP. There cannot be.