What we learned publishing 7 MCP servers to the official registry

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

1. One server per use case, with a tool count your model can handle.
2. Call initialize and tools/list on the real URL, with and without credentials, and read the tool names.
3. title and description within 100 characters, then mcp-publisher validate.
4. Bump version on every change.
5. Log out of the publisher on shared machines.
6. A day later, check how directories show your server, health status included.
7. 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.