Home › Guides › server.json vs mcp.json — which file the registry wants
server.json vs mcp.json — which file the registry wants
Direct answer: they are opposite ends of the same wire. server.json is the publisher manifest: it describes your server to the registry, has a namespaced name, a version, and packages and/or remotes, and it is validated against an official schema. mcp.json is a client config: it tells an app on a user machine which servers to launch, under a top-level mcpServers map. The registry wants server.json — and the validator below detects when you have pasted the other one.
Validate a server.json (or get told you pasted a client config)
Schema problems
| Field | Rule | Problem | How to fix it |
|---|
Extra checks — guidance, not schema rules
Fill in what you have — the file is generated and re-validated as you type. Only include packages or remotes or both, as your server needs.
Packages (local installs)
Remotes (hosted endpoints)
Schema validity is necessary but not sufficient — most registry rejections and silent failures are one of these. Work through the list before you publish. This is guidance, not certification: the registry makes the final decision.
Side by side
server.json | mcp.json (client config) | |
|---|---|---|
| Written by | The server's publisher | The user of a client app |
| Consumed by | The MCP registry (and catalogues downstream of it) | A client application on the user's machine |
| Answers | "What is this server, who publishes it, how is it installed or reached?" | "Which servers should this app start for me, and with what settings?" |
| Telltale shape | name like io.github.you/server, description, version, packages and/or remotes | A top-level mcpServers object whose entries have command, args, env |
| Validated against | The official registry JSON Schema (versioned — this site checks 2025-12-11) | Each client's own conventions; there is no single registry schema |
Why the confusion is expensive
The failure mode is asymmetric. Paste a client config into a registry validator that does not detect it and you get a pile of "missing required field" errors for fields your file was never meant to have — publishers routinely burn an hour "fixing" a file that was fine for its actual job. Paste a server.json into a client as its config and the client silently finds no mcpServers to run: nothing starts, and nothing says why. Detection is cheap — the mcpServers key is unmistakable — so the validator on this page checks for it first and tells you which file you are holding before any schema verdict.
If you are publishing: the shortest correct path
- Write
server.jsonin your project (or generate it in the tool above), with a name in a namespace you can prove is yours. - Validate it against the schema — version printed on the tool, not "latest" by vibes.
- Work the pre-publish checklist (third tab above): matching
mcpName, matching versions, package published first, URLs alive. - Publish with the registry's own flow; bump the version for any later change instead of editing in place.
And if what you actually needed was a config for your editor or desktop client, that file is yours to write by hand — its shape is your client's documentation's business, and no registry will ever grade it.
Frequently asked questions
What is the difference between server.json and mcp.json?
Direction. server.json is written by a server's publisher and consumed by the registry: it describes the server (name in a namespace you own, description, version, packages and/or remotes). mcp.json is written by a user and consumed by a client app: it says which servers to launch locally, under a top-level mcpServers map with command/args/env. Same ecosystem, opposite ends of the wire.
Why do tools keep validating the wrong one?
The names are nearly identical and both are "the MCP JSON file" in casual speech. Several visible tools validate client configs while using server/registry language — so a publisher pastes a valid server.json and gets nonsense errors, or pastes a client config and is told it is "invalid" for registry rules it never claimed to follow. A validator should state which file it checks and detect the other.
Which one do I need to publish my server?
server.json — created in your project, validated against the official registry schema, and submitted with the registry's publisher flow. You only write an mcp.json-style config when documenting how users run your server locally, and it lives in their client setup, not in the registry.