Getting your MCP server listed on Smithery

The smithery.yaml manifest

The smithery.yaml file lives in your repository root and tells Smithery's indexer how to find your server, what it does, and how to run it. It is the single most important file for a successful listing.

# smithery.yaml — place in repository root
startCommand:
  type: stdio
  configSchema:
    type: object
    properties:
      apiKey:
        type: string
        description: "Your API key for the data service"
      region:
        type: string
        enum: ["us-east-1", "eu-west-1", "ap-southeast-1"]
        description: "Target region for data queries"
        default: "us-east-1"
    required:
      - apiKey

# For HTTP/SSE servers, use the url type instead:
# startCommand:
#   type: url
#   url: https://your-mcp-server.example.com/mcp

The startCommand field tells Smithery how to invoke your server. For stdio servers (the most common type for locally-installed MCPs), you provide a type: stdio entry and describe the configuration schema — Smithery uses this to generate an interactive configuration UI when users click "Install". For remote HTTP/SSE servers, use type: url with the public endpoint URL.

The configSchema is a JSON Schema object describing the environment variables or arguments your server accepts. Smithery renders this as a form when a user installs the server through its UI. Well-written schemas — with description fields, enum constraints where applicable, and sensible default values — result in better listings and fewer confused users. Missing required fields with no defaults cause installation failures that show up as user complaints and rating drops.

Package.json metadata Smithery reads

Smithery's indexer reads your repository's package.json (for Node.js servers) alongside smithery.yaml. Several fields influence your listing's display and discoverability:

{
  "name": "@yourorg/mcp-your-server",
  "version": "1.2.0",
  "description": "MCP server for querying your analytics platform — surfaces metrics, funnels, and cohort data directly in Claude.",
  "keywords": [
    "mcp",
    "mcp-server",
    "analytics",
    "metrics",
    "model-context-protocol"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/mcp-your-server"
  },
  "license": "MIT",
  "bin": {
    "mcp-your-server": "./dist/index.js"
  }
}

The description field becomes the short description on your Smithery listing page. Write it from the user's perspective: what can they do with this MCP server? The keywords array feeds Smithery's search index — include mcp and mcp-server as base keywords plus the domain terms users would search for. The bin entry tells Smithery how to invoke your server for stdio mode installations.

For Python servers, Smithery reads pyproject.toml instead. The equivalent fields are project.description, project.keywords, and project.scripts.

What Smithery's crawler verifies

When you submit your server (or when Smithery re-crawls), its crawler performs a real MCP protocol handshake — not just an HTTP ping:

The most common submission failure is a server that responds to a browser GET request (returning an HTML page or a "Server is running" message) but does not handle the actual MCP JSON-RPC requests. Run the verification sequence manually before submitting:

# Quick manual verification — what Smithery's crawler does
curl -X POST https://your-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "smithery-crawler", "version": "1.0.0" }
    }
  }'

# Expect: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}}}

# Then verify tools/list
curl -X POST https://your-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# Expect: {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"...","description":"...","inputSchema":{...}}]}}

If both commands return valid JSON-RPC responses with the correct structure, your server will pass Smithery's crawler. If either fails, fix the issue before submitting — failed crawls do not immediately surface a useful error message to you as the submitter.

Keeping your listing healthy after publication

Smithery re-crawls published listings on a recurring schedule. A server that passes one crawl and then goes down risks getting its verified badge removed or its listing demoted in search results. The crawl schedule is not publicly documented but observed behavior suggests weekly re-crawls with more frequent checks for servers that show a history of instability.

Three things protect your Smithery listing health:

1. External protocol monitoring: HTTP uptime monitors (Pingdom, UptimeRobot) only verify that your server returns HTTP 200 — they do not verify that the MCP initialize handshake succeeds. You can have HTTP 200 and a broken MCP server simultaneously (common when a misconfigured reverse proxy returns 200 for unknown paths). AliveMCP probes the full MCP protocol sequence every 60 seconds and alerts you when the initialize or tools/list response breaks — before Smithery's next crawl discovers the regression.
2. Tool schema stability: Smithery stores a hash of your tools array and flags schema changes as "tool surface drift". Frequent, unannounced changes to tool names or input schemas signal instability to potential users. Version your changes and update your smithery.yaml accordingly.
3. Process supervision: If your server runs on a VPS, use PM2 or systemd to restart it automatically on crash. A 60-second restart window is invisible to users but a 10-minute outage is long enough to be caught by Smithery's re-crawl.

Related questions

Further reading

• Universal MCP registry requirements — what all registries check
• MCP server Glama listing — Glama directory submission guide
• MCP server PulseMCP — PulseMCP discovery and listing
• MCP server tool discovery — how clients find and register your tools
• MCP server health check — verifying your server before registry submission
• MCP server uptime monitoring — keep your listing healthy between crawls
• AliveMCP — 60-second protocol probing so Smithery's next crawl finds your server healthy