One job per tool
If the name needs "and", it is two tools. An agent that must guess which half will guess wrong on the expensive half.
Everything below comes from two places: what the registries actually return, and what server maintainers wrote in public while waiting. No growth hacks, no "10x your installs", no promises about a listing nobody at GitHub has promised.
There are two registries and they behave nothing alike. Publishing to the open one is self-service. Getting into GitHub's β the one that feeds the VS Code MCP gallery β is a manual curation step performed by GitHub.
| Open registry | GitHub registry | |
|---|---|---|
| Address | registry.modelcontextprotocol.io | github.com/mcp Β· api.mcp.github.com |
| Publication | Automated, immediate | Manual curation |
| Versions after first accept | β | Sync automatically |
| Published criteria | Schema validity | Not published |
| Published ETA | Immediate | None |
the GitHub MCP Registry now has the ability to sync versions from the open source registry, but onboarding a new server is still a manual curation process today.
api.mcp.github.com, 2026-10-29Cold truth. Being invisible in the gallery is the default state, not a defect in your code. It does not mean your server is broken, badly written or rejected. It means a human has not looked at it yet.
You cannot speed up the queue. You can remove every reason to skip you when your turn comes. These are the items that appeared as actual blockers in requests published between 2026-10-28 and 2026-10-29.
server.json validates against the current schemaAnd its name matches a namespace you actually own: a GitHub org, or a DNS-verified domain.repository field, or a manifest that replaces itTwo maintainers wrote in their own request that the field was missing. A curator with no source has nothing to check.isLatest: true and a version that matches the packageA superseded version at the latest pointer reads as an abandoned project.title, readOnlyHint, destructiveHint, openWorldHint. Without them a client cannot prompt safely before a write.curl that returns 401 with WWW-Authenticate beats any screenshot.Do not re-post your request. In that thread, one maintainer bumped repeatedly for eight months. The listing arrived after a curator picked it up β not after a bump. Repeated asks add noise to a queue that is read by humans, and noise is the opposite of signal.
A tool description is not documentation for humans. It is the entire decision surface for a model that must pick one of your tools, or none. Write it for the model, and it stays readable for people as a side effect.
If the name needs "and", it is two tools. An agent that must guess which half will guess wrong on the expensive half.
tvijo_review beats process. The name is the first token a
model sees and often the only one it ranks on.
Reject unknown fields rather than ignore them. A silently ignored field is a wrong action the user never sees.
Cap bytes, rows and age. An unbounded result is a context bomb, and it will be your server that gets blamed for the truncated answer.
If you don't know the amount spent, return null and say so. Returning
0 turns an unknown bill into a false receipt.
Every failure gets a stable code and a sentence that tells the agent what to do next. "Something went wrong" forces a retry loop you cannot see.
The moment a tool can spend, the interface changes. An agent with a spend tool and no cap is a bug report waiting for a bill attachment.
spent_usd: null. That is honest; it is not zero.{ "prompt": "Explain how to make this function easier to test.",
"max_usd": 0.25 }
Example from Tvijo DSHREM: default per-call cap 1 USD, hard ceiling 5 USD, paid requests never retried, tokens never returned to the model.
Developer documentation is an interface. These five rules caught more real problems for us than any redesign.
The first screen answers "can I use this in five minutes". Schemas, edge cases and failure codes live one level down, linked, not inline. A page that starts with architecture loses everyone who was still deciding.
A working config block before the explanation of the config block. If a reader has to assemble a config from three sections, three of them will be wrong.
Can a stranger answer: what does it do, what does it cost, what breaks? If one answer is missing, the page is not finished β no matter how pretty it is.
Show the current state instead of describing it: version, sign-in state, remaining limit. A user who can see the state stops guessing and stops writing to support.
One recommended route through the page. Alternate clients and manual setups are exits from that route, not parallel tunnels at the top.
"Fast" is an adjective. "0.2.0 published, registry active, gallery
count: 0, observed 2026-10-29" is a receipt. Receipts survive reviews.
Search ranks pages. An assistant quotes sentences. The unit of work is a claim with a source and a date β not a keyword with a density.
H1, question-shaped H2s, tables for comparisons, FAQ whose questions are the real questions, JSON-LD, llms.txt.Rule of the second pass. If a verdict matches the wording of the question too neatly, check it again with a different instrument. Three models agreeing on the same wrong reading agree confidently.
You can't. It is a manual gate with no published ETA. If a launch depends on it, the launch is already unscheduled. Ship the manual install path as the real path.
If being visible is the whole value, the server has no independent job. A curator notices that, and so does the first user who installs it.
No version, no endpoint, no dated check β then no claim. "It works" is not evidence, and a page built from it will not be quoted.
If users bounce at install, no amount of AEO fixes it. Fix install first; the page only amplifies what is already there.
Free, deterministic, PASS / FAIL / NOT_RUN per item, with the command that produced it. No listing promises β that part is not ours to give.
Open an audit request Read the registry evidence