How to submit an MCP server to ToolSDK MCP Registry

You add one JSON file. A script checks it against a strict schema, a reviewer reads the diff, and the file is merged. The contributing guide is blunt that it is the source of truth, and that the README and the generated indexes are outputs you must not edit to add a server^[1]. Most of the work is picking the right shape for the file.

Where the file goes

• Directly inside packages/<category>/, with a lowercase kebab-case name such as example-mcp.json. Nested folders are not supported. When no category fits, packages/uncategorized is there^[1].
• One server per pull request is preferred. Several from the same publisher are allowed. Anything else in the diff, such as workflows, lockfiles or the README, is out of scope^[1].
• Link the official package or documentation in the description, because the reviewer checks your metadata against it^[1].

A package people install

{
  "type": "mcp-server",
  "name": "Example MCP Server",
  "packageName": "example-mcp-server",
  "description": "Provides example operations for MCP clients.",
  "url": "https://github.com/example/example-mcp-server",
  "runtime": "node",
  "license": "MIT",
  "env": {
    "EXAMPLE_API_KEY": { "description": "API key for the Example service.", "required": true, "secret": true }
  }
}

A local entry needs a public package or Docker image whose name and command can be verified. For Node, leave bin out and the gateway reads the package's own manifest. For Docker, put the image in packageName, set runtime to docker, and write the complete argument list in binArgs. The image and tag must exist^[1]. runtime takes one of node, python, java, go or docker.

A server you host

{
  "type": "mcp-server",
  "name": "Example Remote MCP",
  "packageName": "@toolsdk-remote/example-mcp",
  "description": "Connects to the hosted Example MCP endpoint.",
  "runtime": "node",
  "env": {},
  "remotes": [{ "type": "streamable-http", "url": "https://example.com/mcp" }]
}

• The packageName starts with @toolsdk-remote/, and a name with that prefix must have at least one remote^[1].
• The endpoint is HTTPS, Streamable HTTP, and cannot point at localhost or a private network. Do not set a custom key^[1].
• runtime: "remote" is not valid. Use the implementation's runtime, or node for a hosted-only server^[1].

Run the registry's own validator

git fetch origin main
node scripts/validate-registry.mjs --base origin/main

It uses only Node's built-ins, checks the files your branch changed, and compares identities with the current base. The guide warns against make build as a check, because that installs and runs registry packages^[1].

What fails the check

• An unknown field. The package JSON is strict, and unknown fields are rejected^[1].
• An identity that already exists. A new file cannot reuse a key, or a packageName when there is no key, that is on main. Deleting the old file in the same pull request does not help^[1].
• A secret with a default. A variable marked secret cannot define one^[1].
• Extra files in the diff. Mixing package JSON with documentation, source, workflow or generated files fails with OUT_OF_SCOPE_CHANGE and goes to manual review^[2].

The review, and the route by hand

Review is deterministic JSON validation against main. The reviewer never installs or runs a submitted package or probes a remote service, so your metadata has to be right on its face^[2][1]. By hand, that is one fork, one file, one validator run and one pull request that links your docs. Merges are squashed^[2].

Current status, 1 Oct 2026

On 2 Oct 2026 the registry had 80 open pull requests^[4], and its last push was dated 15 Sept 2026^[3].