DEV Community: Zebu Data

What we learned publishing 7 MCP servers to the official registry

Zebu Data — Sat, 10 Oct 2026 15:19:05 +0000

The official MCP Registry is where MCP clients and directories look up servers, so if you build one, you want it listed there. We build web scrapers on Apify and wrap groups of them as remote MCP servers, and over the last two weeks we published 7 of them: 4 on Oct 1, then 3 more on Oct 7, when we also updated 3 of the first 4. Here's what we ran into, with the real limits and errors.

1. Decide what one server should hold

Our first instinct was one big server with every tool. We split them by use case instead: local business leads, customer reviews, YouTube data and so on. Each one holds between 2 and 7 tools.

Two reasons:

Models pick the wrong tool less often when they only see a handful of similar ones.
Your gateway may add tools of its own. Ours adds 4 helper tools to every server, for checking a job, paging through results, reading a file and stopping a job. A 7-tool server shows up as 11 tools in tools/list.

There's a side benefit: each server gets its own listing, so someone searching a directory for "reviews" or "YouTube" finds the one that matches.

2. server.json has hard limits

A minimal remote entry looks like this:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.your-user/your-server",
  "title": "Your Server",
  "description": "One sentence about what the tools do.",
  "version": "1.0.0",
  "websiteUrl": "https://example.com",
  "remotes": [{ "type": "streamable-http", "url": "https://mcp.example.com/mcp" }]
}

The 2025-12-11 schema caps title and description at 100 characters each, and name must look like namespace/server: letters, digits, dots and dashes, plus underscores after the slash. Our first description was 106 characters. We caught it with a length check in our build script, but mcp-publisher validate server.json catches it too, and it checks against the live registry.

3. Your namespace comes from your GitHub login

For io.github.<user>/... names, the publisher authenticates you through GitHub with a device code:

mcp-publisher login github      # shows a code to enter at github.com/login/device
mcp-publisher validate server.json
mcp-publisher publish server.json
mcp-publisher logout

Approve the code while signed in as the account that owns the namespace. One login covers as many publishes as you need. If you're on a shared machine, log out when you're done so the token doesn't stay on disk. We also checked the binary's SHA-256 against the release's checksums file before running it, since it handles a GitHub token.

4. An update is a new version, and the old one stays

To change a server you publish it again with a higher version. The registry keeps both: after our update, local-business-leads showed 1.0.0 with isLatest: false and 1.1.0 with isLatest: true, both still active. Clients that read the registry should take the latest, but don't assume an old version disappears.

The public API can also be slow. A search that returns two entries took about 23 seconds for us, so give scripts a generous timeout.

5. Keep tool names under 64 characters

Our gateway names each tool owner--tool-name. One of ours came out at 66 characters, so it was cut to 64 and given a short hash suffix:

...--ebay-product-reviews-scraper-with-advanced--60e9

The cut isn't arbitrary: model APIs such as OpenAI's and Anthropic's only accept tool names up to 64 characters. The model still gets the tool, but with a name that's harder to match to a user's request. If you control the underlying names, keep them short.

6. Directories list you automatically, and may call you unhealthy

We never submitted anything to Glama, but it picked up all our servers from the registry within about a day, and later picked up our updated descriptions too.

Every one of them is marked Unhealthy. Glama's checker connects without credentials, and our servers require the user to sign in (OAuth), so the check can't get past the start. The fix is to claim the listing and add a test profile that Glama uses only for health checks. If you do that, give it a limited credential, not your main one.

7. Awesome lists have rules, and a queue

awesome-remote-mcp-servers is the main curated list for remote servers. Its CONTRIBUTING.md asks for:

an endpoint that answers an MCP initialize request, which CI checks on every PR,
a Glama connector badge, which CI also checks,
a star on the repo from the account opening the PR,
one server per PR, in alphabetical order, with a description of up to 120 characters ending in a period,
a marker for the auth type: none, API key or OAuth.

What surprised us was the queue. For almost a week after we opened our PR, nothing in the repo was merged at all. Then the maintainer merged almost 400 PRs in a few days, and ours wasn't one of them: other entries had landed next to ours in the same section, so it now had a merge conflict. A comment on the PR asked us to rebase or merge the latest main first. If you submit, watch your PR and fix conflicts fast, because merges come in batches.

One more trap: the badge check calls Glama. When Glama was briefly down, our PR failed with "no such connector". Editing the PR description re-ran the checks once it was back.

8. A checklist before you publish

One server per use case, with a tool count your model can handle.
Call initialize and tools/list on the real URL, with and without credentials, and read the tool names.
title and description within 100 characters, then mcp-publisher validate.
Bump version on every change.
Log out of the publisher on shared machines.
A day later, check how directories show your server, health status included.
For curated lists: one PR per server, then keep an eye on it.

Are you publishing MCP servers too? We'd like to know which directories your users actually find you through.

Written with AI assistance.

Remote MCP tools that run long: what your agent actually gets back

Zebu Data — Fri, 02 Oct 2026 17:22:01 +0000

Most MCP demos show a tool that answers in a second. Real tools often don't: a scraper, a crawl or a report job can take minutes. We build web scrapers on Apify, so this is a problem we run into daily. We wanted to know what an agent actually receives when a remote MCP tool runs longer than one call, so we traced the raw JSON-RPC traffic against Apify's hosted MCP server (mcp.apify.com, version 0.17.1 at the time) on Oct 2, 2026. The job: a YellowPages scraper reading one results page, which takes about 35 seconds.

1. Discovery: one tool per job, plus helpers

After initialize, tools/list returned one tool per scraper we had allowed through the server URL, plus four helper tools that only make sense for long-running work:

get-actor-run checks a run's status and can wait for it,
get-dataset-items reads the results in pages,
get-key-value-store-record reads a stored file or record,
abort-actor-run stops a run.

The helpers are the first hint: the server expects the agent to come back for results.

2. The call returns early

The agent calls the scraper tool with ordinary arguments:

{ "searchKeyword": ["plumbers"], "location": "Austin, TX", "maxPages": 1 }

The response arrived after about 30 seconds, while the job was still running. It had two content parts. The first is structured:

{
  "runId": "…",
  "status": "RUNNING",
  "storages": { "datasets": { "default": { "id": "…", "itemCount": 23 } } }
}

The second is plain text written for the model:

RUNNING for 30s. In progress. 23 results so far.
Use get-actor-run with runId=… and waitSecs=30 to poll for completion.

That second part is the interesting design choice. The server returns machine-readable state and also tells the model, in plain English, what to do next. An agent that only parses the JSON still works. An agent that only reads text also knows to poll.

3. Polling has a ceiling

We first asked get-actor-run to wait 60 seconds and then 120. Both came back as a JSON-RPC error, not a tool result:

MCP error -32602: Invalid arguments for tool "get-actor-run".
Validation errors: /waitSecs: must be <= 45.

With waitSecs: 30 the call returned SUCCEEDED, the run time (about 35 seconds) and the dataset item count (37). The result also carried a _meta block with the run's platform usage, which a client can show the user before it starts anything bigger.

Two things to handle here:

Validation problems arrive as protocol errors (-32602), not as tool results with isError. If your client only checks isError, it will miss them.
The wait is capped, so a five-minute job means several polls. Your loop needs a total deadline, not just a per-call wait.

4. Reading results in pages

get-dataset-items takes the dataset ID plus offset and limit, and returns:

{ "datasetId": "…", "items": [ … ], "itemCount": 37, "totalItemCount": 37, "offset": 0, "limit": 100 }

For a big job, page through with offset instead of pulling everything into the model's context at once.

5. The trap: SUCCEEDED with zero items

The same evening a second test job, a Google Maps scraper, ran for about 157 seconds and finished with status SUCCEEDED, but get-dataset-items came back empty:

{ "items": [], "itemCount": 0, "totalItemCount": 0, "offset": 0, "limit": 100 }

An upstream dependency was failing, and the job ended cleanly with nothing to show. If your agent treats SUCCEEDED as "done, report success", it will tell the user everything worked. Check the item count, and treat "succeeded but empty" as a result the user needs to hear about.

A checklist for long-running MCP tools

Expect an early return. Store the run ID the first response gives you.
Poll within the server's limits (45 seconds per wait here), with an overall deadline and a clear message if it runs out.
Check protocol errors and isError. They come back in different places.
Read results in pages to protect the context window.
Treat "succeeded, zero items" as a warning, not a success.
Abort what you no longer need. If the user changes the question halfway, abort-actor-run saves the rest of the job's cost.
Expose fewer tools. A server-side allow list keeps the model from picking the wrong tool and limits what it can touch.

How does your MCP client deal with tools that outlive one call: polling, progress notifications, or something else? We're curious what holds up in production.

Written with AI assistance. Every request and response above comes from real calls we made on Oct 2, 2026.