The Model Context Protocol (MCP) enables AI agents and tools to connect with external systems through MCP servers. As developers build more servers, discoverability becomes key: How do you make yours easy for others to find and use?

Enter the MCP Registry—a public directory for MCP-compatible servers.

In this step-by-step guide, learn:

What the MCP Registry is and its role in MCP workflows
How to prepare and test your MCP server before publishing
The full process to publish an MCP server successfully
How MCP Playground streamlines testing in modern MCP development

What Is the MCP Registry?

The MCP Registry serves as a public directory listing MCP-compatible servers. It helps:

MCP clients discover available servers
Developers review tools and capabilities
AI frameworks integrate servers seamlessly

This acts as a central discovery hub for the Model Context Protocol ecosystem.

📘 MCP Registry docs: https://registry.modelcontextprotocol.io/docs

Why Publish to the MCP Registry in 2025?

AI agents, tool-using LLMs, and agent frameworks (local and cloud) are proliferating. Hardcoding server configs doesn't scale for broader use.

Listing in the MCP Registry provides:

Improved discoverability for MCP clients
Standardized metadata for tools and transports
Simplified adoption without custom setups
Increased trust through public verification

Essential if you want your MCP server used beyond your team.

Prerequisites for Publishing an MCP Server

Ensure these are ready before submission:

Fully Functional MCP Server

Implements MCP protocol correctly
Exposes tools with valid JSON schemas
Supports at least one transport: stdio (local), HTTP, or SSE (remote)

Complete Metadata

Server name, description, and supported transports
Tool definitions
Repository or docs link

Accurate metadata shapes how your server appears in searches and listings.

How to Test Your MCP Server (Avoid Common Pitfalls)

Skipping client-side testing leads to issues like failed tool discovery, schema errors, or broken agent workflows.

MCP Playground offers a free, browser-based tester—no custom client needed. Key features:

Connect directly to local or remote MCP servers
Simulate real MCP client interactions
Trigger tools manually
Inspect raw requests/responses
Validate schemas visually

👉 Test your MCP server in MCP Playground →

This replicates real-world client behavior.

A Practical MCP Server Testing Workflow

Step 1: Build Your MCP Server

Start by implementing your MCP server with a focus on:

Correct MCP protocol handling
Well-defined tool schemas
Predictable, schema-valid responses

At this stage, prioritize correctness over optimization.

Step 2: Validate Behavior Using MCP Playground

Once your MCP server is reachable over a supported transport (such as HTTP or SSE), you can use MCP Playground Online to validate client-side behavior.

With MCP Playground, you can:

Discover exposed tools
Send tool requests
Inspect raw MCP messages
Validate input and output schemas

This helps catch common issues that MCP clients face during integration.

Note: Browser-based testing applies to MCP servers exposed over network-accessible transports.

Step 3: Test Remote Deployments

For remotely deployed MCP servers:

Test them again via MCP Playground
Validate:
- Network reliability
- Authentication flows (if applicable)
- Error handling and edge cases

This step ensures your server behaves correctly when accessed by external MCP clients.

How to Publish to the MCP Registry

Ready to publish? Here's the complete process, with automated CI workflows preferred over manual steps.

Step 1: Create Your server.json File

First, create a server.json file in your MCP server repository root. This file contains all the metadata about your server.

Here's a basic example structure:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.github.yourusername/your-server-name",
  "title": "Your Server Title",
  "description": "A clear description of what your MCP server does",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "name": "your-server-package",
      "version": "1.0.0"
    }
  ],
  "remotes": [
    {
      "url": "https://your-server-url.com/mcp",
      "transport": "http"
    }
  ]
}

Key fields to include:

$schema: Points to the official MCP Registry schema for validation
name: Unique identifier in format namespace/server-name
title: Display name for your server
description: Clear explanation of your server's purpose
packages: Package registry information (npm, PyPI, etc.)
remotes: Remote server URLs and transport types (if applicable)

Step 2: Validate Your server.json

Before publishing, validate your server.json against the official schema. This prevents submission errors.

Option A: Validate with JSON Schema Validator (Recommended)

You can validate your schema using online tools or command-line validators:

# Using Node.js and ajv-cli (if installed)
npx ajv-cli validate -s https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json -d server.json

# Or using Python with jsonschema
pip install jsonschema
python -c "import json, jsonschema, urllib.request; schema = json.loads(urllib.request.urlopen('https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json').read()); data = json.load(open('server.json')); jsonschema.validate(data, schema); print('Valid!')"

Option B: Use Online Validators

Copy your server.json content
Use a JSON Schema validator like JSON Schema Validator
Paste the schema URL and your JSON to validate

Step 3: Publish via GitHub Actions (Automated - Recommended)

For automated publishing, set up a GitHub Actions workflow that validates and publishes your server on each release or version tag.

Create .github/workflows/publish-registry.yml in your repository:

name: Publish to MCP Registry

on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate server.json
        run: |
          # Install validation tool
          npm install -g ajv-cli
          # Validate against schema
          ajv validate -s https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json -d server.json
      
      - name: Publish to Registry
        uses: modelcontextprotocol/registry-action@v1
        with:
          server-json-path: ./server.json
          github-token: ${{ secrets.GITHUB_TOKEN }}

Benefits of automated publishing:

✅ Automatic validation before publishing
✅ No manual steps required
✅ Consistent publishing process
✅ Integrated with your release workflow

Step 4: Manual Publishing (Alternative)

If you prefer manual publishing or don't use GitHub:

Fork the MCP Registry repository
Add your server.json to the appropriate directory
Create a pull request with your server metadata
Wait for review and approval

Step 5: Verify Your Listing

After publishing, verify your server appears in the MCP Servers List. Search for your server by name or namespace to confirm it's discoverable.

Pro tip: Test your published server using MCP Playground to ensure it works correctly for end users.

Best Practice: Add Live Testing Links

Link your registry entry to a live MCP Playground test instance. This lets users:

Discover your server
Test instantly
Gain confidence before integrating

Boosts adoption and trust.

Key Takeaways

Use the MCP Registry for discoverability
Test rigorously with MCP Playground
Follow the workflow for rejection-free publishing
Build MCP servers that AI agents and developers rely on

Ready to test your MCP server? Test it now on MCP Playground →

How to Publish Your MCP Server to the MCP Registry (Step-by-Step Guide)