Get Your MCP Server Discovered: Registry and Directories

To get your MCP server, agent or skill discovered, make it easy to find in the places developers already search and easy to trust once they land on it. In practice: write a README that explains what it does in the first lines, add a machine-readable manifest (server.json for MCP servers, SKILL.md for skills), publish to the official MCP Registry, list in a few relevant directories and marketplaces, add GitHub topics, and show a short demo and a security report.

None of this guarantees users. But each step removes a reason someone might skip your project. This guide goes through them in order of impact. It is part of our guide on how to sell AI agents, MCP servers and skills, and it applies whether your project is free or paid.

Write a README that answers three questions fast

Most people decide in seconds whether to keep reading. The top of your README should answer:

1. What does it do? One sentence. Name the tools it exposes or the job it handles.
2. Who is it for? Which client (Claude Desktop, VS Code, Cursor, others) and which use case.
3. How do I install it? A copy-paste config block or command.

Explain what the server does in one line, then link a primer such as what is an MCP server for newcomers.

Then add the details that careful users look for:

• Tool list. Each tool's name, what it does, and its inputs.
• Configuration. Every environment variable, which ones are secrets, and where to get them.
• Permissions. What files it reads or writes and which network domains it contacts.
• Requirements. Runtime version, operating systems, any paid API accounts.
• License. Stated plainly, with a LICENSE file in the repo.
• Changelog or releases. Proof the project is maintained.

Write tool descriptions carefully. MCP clients pass tool descriptions to the model, so they should be accurate and free of hidden instructions. Misleading descriptions are the core of MCP tool poisoning, and security-aware users read them.

Add a manifest file

A manifest lets registries, marketplaces and clients read your project's metadata without guessing.

server.json for MCP servers

The official MCP Registry uses a server.json file. It holds your server's name, description, version, repository, and how to run it: the package (npm, PyPI, NuGet, Docker and others) and transport. It can also list environment variables and mark which are secrets. The mcp-publisher init command generates a template. See the MCP Registry quickstart for the current schema.

SKILL.md for agent skills

An agent skill is a folder with a SKILL.md file. Its YAML front matter needs at least a name and a description. Agents load only those two fields at first and pull in the full file when a task matches, so the description is how your skill gets picked. Write it as a clear statement of when to use the skill. The Agent Skills site has the format, and our SKILL.md format explainer walks through it.

Agent manifests

There is no single manifest standard for agents yet. If your agent speaks the A2A protocol, it should publish an agent card, which the A2A discovery docs place at /.well-known/agent-card.json. Some directories, including AgenticMart, also look for an agent.json in the repo to classify it. Whatever you use, declare the network domains and environment variables your agent needs.

How do I publish to the MCP Registry? Step by step

The MCP Registry is the official, community-built registry for MCP servers. A few facts worth knowing, from the official quickstart:

• It is in preview. Breaking changes or data resets may happen before general availability.
• It hosts metadata only, not your code. You publish the package to npm, PyPI or another package registry first.
• Names are namespaced. With GitHub login, your server name must start with io.github.<your-username>/. DNS-based authentication lets you use your own domain as the prefix.
• Remote servers are supported, so you can list a hosted server, not just a package.

1. Add the ownership marker to your package

The registry checks that the package matches your server.json. For npm, add an mcpName field to package.json with the same value as name in server.json. For PyPI and NuGet, put an mcp-name: <server-name> line (or HTML comment) in the package README (quickstart troubleshooting table; other types are covered under package types). Then publish the package as usual.

2. Install mcp-publisher

On macOS or Linux you can use Homebrew:

brew install mcp-publisher
mcp-publisher --help

The quickstart also has a curl one-liner for macOS and Linux and a PowerShell command for Windows that download the binary from the registry's GitHub releases. The CLI has init, login, logout, publish, status and validate commands.

3. Create and check server.json

Run mcp-publisher init to generate a template, then edit it. Two rules catch people out:

• The description field is limited to 100 characters. Longer descriptions fail validation.
• name must match your package's ownership marker exactly.

Run mcp-publisher validate to check the file without publishing.

A remote-only server needs no package. Replace the packages array with remotes (this example is from the quickstart):

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "title": "Weather",
  "description": "A remote MCP server for weather information.",
  "repository": {
    "url": "https://github.com/my-username/mcp-weather-server",
    "source": "github"
  },
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://weather.example.com/mcp"
    }
  ]
}

The remote URL must be publicly reachable. The registry verifies that you control the namespace in name, but it does not verify that you control the remote URL.

4. Log in and publish

mcp-publisher login github
mcp-publisher publish

Use mcp-publisher status later to update the status of a server version. The docs also describe automating publishing with GitHub Actions so each release updates the registry.

5. Check the listing

Search the registry API for your server name:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"

Your server's metadata should appear in the servers array.

Troubleshooting

These errors and fixes come from the quickstart:

Error	Fix
"Registry validation failed for package"	Add the ownership marker for your package type (mcpName for npm, an mcp-name: README line for PyPI and NuGet).
"Invalid or expired Registry JWT token"	Run mcp-publisher login github again.
"You do not have permission to publish this server"	Your login method does not match the namespace. With GitHub login, the name must start with io.github.your-username/.

Server Cards and well-known discovery

For remote servers there is now a way to be found before anyone connects. SEP-2127, MCP Server Cards, has Final status. A Server Card is a static, public JSON document that describes a remote server: its name, version, description, transport endpoints and supported protocol versions. It does not list tools, resources or prompts, because those can change per user and are only reliable at runtime.

• The recommended location for a card is <your-streamable-http-url>/server-card.
• For domain-level discovery, you can publish an AI Catalog at /.well-known/ai-catalog.json that links to or embeds your cards.
• Cards are optional. Servers without one keep working normally.

Never put credentials or user-specific data in a card; the SEP says cards are public by design. The exact field set lives in the Server Card extension repository.

server/discover: discovery inside the protocol

The 2026-07-28 MCP revision removed the initialize handshake and added server/discover, which servers MUST implement to advertise their supported protocol versions, capabilities and identity. Clients may call it before any other request. If you build on an SDK that supports 2026-07-28, check that your server answers modern clients before you publish, for example with the MCP Inspector. Server Cards and server/discover overlap, and the SEP says clients should prefer the live server/discover values if they disagree.

List in directories and marketplaces

Beyond the official registry, there are community directories for MCP servers and skills, and marketplaces where you can sell. Pick a few that fit your audience rather than submitting everywhere. For each, check:

• Does it link to your repo and show your README?
• Does it show install instructions for common clients?
• Can you update the listing yourself, or claim it if someone else added it?
• Does it show any security signal, such as a scan report?

Where	What it checks before listing
MCP Registry	That you control the namespace in name and, for packages, that the package carries a matching ownership marker. It does not verify control of a remote URL (quickstart).
AgenticMart	Nothing is required to list. Any listing can get a free automated scan; each listing page shows its scan status (how scans work).
GitHub topics	Nothing. Topics are labels you set yourself (GitHub docs).

On AgenticMart you can submit a repo for free and request a free automated scan. If your repo was already imported, maintainers with admin or maintain permission can claim the listing by signing in with GitHub. Listings appear by type, such as MCP servers, agent skills and agents, and in categories. Publishers can read how listings and scans work on the developers page.

Keep your name and one-line summary the same across every listing.

Use GitHub topics and a clear repo description

GitHub search and topic pages are a major discovery path for developer tools. Topics are labels on your repo that help people find it. Add relevant ones like mcp, mcp-server, model-context-protocol, agent-skills, ai-agents, plus the services you integrate with.

Also set:

• A repo description that matches your one-sentence summary.
• A website link to your docs or demo.
• Releases with notes, so people can see activity.

Write docs that rank and help

A README covers the basics. Separate docs pages help with search and with real use:

• One page per client setup. People search for exact phrases like the client name plus your service name.
• Use-case guides. Short pages that show a task from start to finish.
• Troubleshooting. Real error messages and fixes.

Our post on building your first MCP server shows the parts users expect to see documented.

Show a demo

A short screen recording or GIF of the agent doing a real task answers "does this work?" faster than any text. Put it near the top of the README. Show the setup too, not just the result. If you host a remote server, a free tier or sandbox key lets people try it without risk.

Show what it can access

Being found is half the job; being chosen is the other half. Make that choice easier:

• Declare permissions and network domains in your manifest and README.
• Keep secrets out of the repo and dependencies patched.
• Link to a public security report or show a badge.

On AgenticMart, any listing can get a free automated scan; each listing page shows its scan status. The scan covers static analysis, secret detection, dependency vulnerabilities, an install-and-boot test in a locked-down container, and network egress compared to your declared domains, with a public report and a 0 to 100 score. You can read how the scan works. A clean scan is not a safety guarantee. Whichever tools you use, publishing the results lets users check for themselves.

Keep it fresh

Stale projects lose ranking and trust. Ship small updates, answer issues, and keep the registry entry version in sync with your package. A visible maintenance rhythm is one of the strongest signals you can send.

FAQ

How do I publish my MCP server to the official registry?

Publish your package to a supported package registry such as npm or PyPI, add the ownership marker (for npm, an mcpName field), then use the mcp-publisher CLI to create server.json, log in, and publish. The registry is in preview, so check the official quickstart for current steps.

Do I need a server.json if I am not using the registry?

It is not required, but it helps. A manifest gives directories, marketplaces and security scanners a reliable place to read your name, version, environment variables and how to run the server. It also signals that the project is well maintained.

What GitHub topics should an MCP server use?

Use the general ones, such as mcp, mcp-server and model-context-protocol, plus topics for the services and use cases you cover. Keep them accurate. Irrelevant topics bring the wrong visitors and do not help.

What is an MCP Server Card?

A static JSON document, defined in SEP-2127, that tells clients and crawlers where a remote MCP server lives and which protocol versions it supports, before they connect. The recommended location is <your-mcp-url>/server-card.

Why does mcp-publisher reject my server.json?

The most common causes in the official troubleshooting table are a missing ownership marker and a name outside your login namespace; a description over 100 characters also fails validation. Run mcp-publisher validate to see the error before publishing.

Will a security badge get me more users?

No badge guarantees users. But many developers check safety before installing code that touches their files or network, and a public report answers that question quickly. It removes a reason to skip your project.