MCP Cursor Guard

MCP Cursor Guard is a small, focused tool for people who build MCP (Model Context Protocol) servers that page through records. Its job is to make pagination trustworthy: instead of handing out a plain offset cursor that can be replayed against any filters, the library issues cursors that carry a signed, expiring fingerprint of the filters that produced them. The project is described by its maker as the fix for a paging bug in MCP servers, and it ships in two parts — a free MIT-licensed cursor library published on npm as mcp-cursor-guard, and a paid production kit that adds the operational pieces around it. It is placed by its author in the LLM developer tools and developer tools space rather than in the hands of end users. The problem it addresses is a silent failure. As the maker explains, MCP pagination fails silently when an agent replays an offset cursor against different filters. In the incident that prompted the project, an MCP server was returning valid-looking pages of records that answered a different question than the one asked: the agent replayed a plain offset cursor against new filters, and nothing told anyone the page was wrong. Nothing in the response signalled that the slice no longer matched the query. The maker says they built the project after losing a full afternoon to the same bug. For anyone shipping an MCP server to LLM agents, that is the dangerous part — the failure is not a crash or a clear error, it is a plausible-looking page of records that answers something else. The core fix is to make the cursor self-describing. In MCP Cursor Guard the cursor now carries a signed, expiring fingerprint of the filters that produced it. Because the fingerprint is signed, a server can verify that the cursor it receives was one it issued; because the fingerprint is bound to the original filters, the server can compare those filters with the current request. The expiry adds a time boundary to the cursor's life. Taken together, these three properties — signed, expiring and filter-bound — mean the cursor is no longer a free-floating offset that any agent can reuse against any query. It is a token that describes the exact query context it belongs to, so the server always has enough information to decide whether the page being requested is still legitimate. When a mismatch is detected — a cursor replayed against different filters — the library throws invalid_cursor rather than quietly returning a page. That converts a silent, hard-to-diagnose bug into an explicit, catchable error. Alongside the cursor change, every response reports matched / returned / complete, so a model can tell a slice from the whole set. In practice that means an agent, or the developer debugging it, can see how many records matched the query, how many were returned in this page, and whether the result set is complete — three numbers that distinguish a partial page from a finished one and remove the guesswork about whether there is more to fetch. The cursor logic itself is MIT licensed and free on npm under the package name mcp-cursor-guard. Alongside the package there is a runnable demo, invoked with npx mcp-cursor-demo-server, and the demo server is published on GitHub. The demo exists so developers can see the behaviour — including the invalid_cursor mismatch — without wiring the library into their own server first. The free package contains the cursor logic; that is the part the maker released openly and the part that fixes the described paging bug, which is why it is available without payment. The production kit covers the surrounding work. Per the maker, it adds scoped bearer auth, per-token rate limiting, stdio plus Streamable HTTP transports, and a 31/31 test suite. Those are the operational pieces an MCP server needs once it is exposed to real clients: authentication that is scoped rather than all-or-nothing, limits applied per token, a choice between stdio and Streamable HTTP as the transport, and a test suite that passes in full. It is sold at legaza.gumroad.com/l/mcp-kit for 79 EUR as a one-time payment with no subscription, and the maker discloses plainly that they wrote it and sell it. The approach is narrow on purpose: rather than changing how an MCP server stores or queries records, the library changes what a cursor is. A cursor stops being a positional offset and becomes a signed statement about the filters that produced it, with an expiry attached. Verification happens when the cursor comes back, and any disagreement surfaces as invalid_cursor. The record envelope then carries matched / returned / complete so the consumer can interpret the page it just received. This is a correction at the level of the cursor contract that sits between the server and the agent, which is why the same small library applies to any MCP server that paginates: the fix lives in how pages are identified, not in the data layer underneath. The benefit the maker emphasises is diagnostic clarity. Instead of pages that look valid but answer a different question, you get an explicit invalid_cursor; instead of guessing whether a page is a slice or the whole set, the response reports matched / returned / complete. For teams building LLM developer tools, that means fewer afternoons lost to a bug that hides behind plausible output, and a failure mode that announces itself rather than corrupting the results an agent reasons over. The free MIT library means the fix can be adopted at no cost, and the paid kit is there for those who also want auth, rate limiting, transports and a full test suite rather than assembling them. Concrete scenarios come straight from the described failure. An agent pages through a list of records, the user or the agent changes a filter, and the agent replays the previous cursor — with MCP Cursor Guard the server rejects the replay with invalid_cursor instead of serving records from the wrong set. A developer testing a paginating MCP server runs npx mcp-cursor-demo-server to watch the mismatch behaviour and the matched / returned / complete envelope before integrating the library. A team taking an MCP server toward production uses the kit's scoped bearer auth, per-token rate limiting and stdio or Streamable HTTP transport, with its 31/31 tests as the starting point. MCP Cursor Guard is for developers building MCP servers and the LLM developer tools around them — the listing places it under LLM Developer Tools, Open Source and Developer Tools, and the maker's note is addressed to whoever maintains the MCP server where the paging bug lives. Distribution is via npm (mcp-cursor-guard) and npx for the demo (mcp-cursor-demo-server), with the demo server on GitHub and the production kit on Gumroad. Pricing is split: the cursor logic is MIT and free, the demo is free, and the production kit is 79 EUR as a single payment with no subscription. The value proposition is specific rather than sweeping: MCP pagination fails silently when an offset cursor is replayed against different filters, and MCP Cursor Guard replaces the offset with a signed, expiring, filter-bound cursor so that mismatch throws invalid_cursor and every response reports matched / returned / complete. The cursor logic is free and MIT licensed on npm with a runnable demo; the production kit adds scoped bearer auth, per-token rate limiting, stdio and Streamable HTTP, and 31/31 tests for 79 EUR, one payment. It is a small, targeted correction to the pagination contract of MCP servers.