How to Pre-Flight Your MCP Server Before Publish

Preflight by Skillfoundry · April 2026

You've built an MCP server. It works locally. You're ready to list it on Smithery, AgenticMarket, or the npm MCP registry. But before you hit submit, there's a set of checks that every registry runs — and most builders don't know about them until their listing gets rejected.

This guide walks through each check and how to make sure your server passes.

1. server.json — the file registries actually parse

Your server.json is the single most important file for registry listing. It's not just metadata — registries use it to decide whether to accept, surface, or rank your server. Here's what gets checked:

• name: Must be present, non-empty, and match your package name. Registries reject mismatches silently.
• description: Most registries require at least 20 characters. One-word descriptions get flagged. Describe what the server does for the user, not what it is internally.
• version: Must be valid semver. Pre-release tags (e.g. 0.1.0-beta) are accepted but may be deprioritized in search.
• homepage: A working URL. This isn't optional — registries that auto-generate listing pages pull the homepage link prominently. A 404 or missing homepage field is a common rejection trigger.

2. smithery.yaml — if you're targeting Smithery

Smithery has its own configuration format. If you're publishing there, the smithery.yaml file tells Smithery how to build and run your server. Key requirements:

• startCommand: The exact command to start your server. Not npm start if your actual entrypoint is different.
• configSchema: If your server accepts configuration, the schema must be valid JSON Schema. An invalid schema doesn't just get rejected — it prevents the configuration UI from rendering.
• Build context: Smithery builds your server from source. If your Dockerfile or build script assumes local paths or secrets, it will fail in Smithery's build environment.

3. Registry slug and naming rules

Each registry has its own slug rules. Smithery derives a slug from your package name. AgenticMarket lets you set one. The npm MCP registry uses the npm package name directly. Common problems:

• Slug collisions — someone already has your name.
• Invalid characters — underscores, spaces, or uppercase in slugs that require lowercase-hyphenated format.
• Mismatched slugs across registries — not a rejection, but it fragments your discoverability.

4. The checks automated tools can run for you

Some of these checks are mechanical — does the field exist, is the URL live, is the schema valid. These are exactly the checks that Preflight runs automatically.

Preflight is an MCP tool that audits your server package against live registry rules. You pass it your server.json (and optionally smithery.yaml), and it returns a verdict: either checks_pass or fixable with specific rules flagged and fixes prioritized.

# Example: check your server via curl
curl -X POST https://preflight.skillfoundry.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"preflight_check","arguments":{"server_json_url":"https://your-server.com/server.json"}}}'

5. What to do when checks fail

Fix the specific field that's flagged. Re-run the check. Don't submit until you see checks_pass. Registry reviewers (human or automated) see exactly the same issues — submitting with known failures wastes your time and theirs.

For issues that automated checks can't catch — trust signals, packaging edge cases, or registry-specific quirks — a manual compliance review catches what tooling misses.

Check your server with Preflight