Skip to main content
Publish your MCP server to Smithery Gateway for distribution, analytics, and OAuth UI.
Bring your own hosting — Smithery Gateway proxies to your upstream server.
  1. Go to smithery.ai/new
  2. Enter your server’s public HTTPS URL
  3. Complete the publishing flow

​
Requirements

  • Streamable HTTP transport
  • OAuth support (if auth required)
No client registration needed. Smithery handles client registration automatically via Client ID Metadata Documents.
Need a framework or hosting? Build MCP servers with xmcp or host them on Gram — both work with Smithery’s URL publishing.

​
Server Scanning

Smithery scans your server to extract metadata (tools, prompts, resources) for your server page.
  • Public servers: Scan completes automatically
  • Auth-required servers: You’ll be prompted to authenticate so we can complete the scan
If automatic scanning can’t complete (auth wall, required configuration, or other issues), you can provide server metadata manually via a static server card at /.well-known/mcp/server-card.json:
{
  "serverInfo": {
    "name": "Your Server Name",
    "version": "1.0.0"
  },
  "authentication": {
    "required": true,
    "schemes": ["oauth2"]
  },
  "tools": [
    {
      "name": "search",
      "description": "Search for information",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ],
  "resources": [],
  "prompts": []
}
Fields:
  • serverInfo (required): Server name and version
  • authentication (optional): Auth requirements and supported schemes
  • tools, resources, prompts (optional): Capability definitions per MCP spec
The schema follows types from @modelcontextprotocol/sdk/types.js. See SEP-1649 for the spec proposal.
You can also publish a URL-based server via CLI with a custom config schema:
smithery mcp publish "https://your-server.com/mcp" -n @your-org/your-server
To specify a config schema, pass it as a JSON string:
smithery mcp publish "https://your-server.com/mcp" -n @your-org/your-server --config-schema '{"type":"object","properties":{"apiKey":{"type":"string"}}}'
See Session Configuration for JSON Schema format with x-from extension.

​
Troubleshooting

​
403 Forbidden during scan

If your deployment fails with “Initialization failed with status 403”, it means your server rejected Smithery’s scan request. Common causes:
  • WAF or bot protection (e.g. Cloudflare Bot Fight Mode) blocking automated requests
  • Server returning 403 for unauthenticated requests instead of 401 — per the MCP auth spec, servers should return 401 to trigger OAuth discovery
  • IP-based access restrictions or allowlists that don’t include Smithery’s IP range
Smithery sends requests with User-Agent SmitheryBot/1.0 (+https://smithery.ai). These requests originate from Cloudflare Workers, which some WAF configurations block by default.

​
Option 1: Ensure your server returns 401 (not 403) for OAuth

If your server requires OAuth, make sure it returns 401 Unauthorized (not 403 Forbidden) for unauthenticated requests. Smithery uses the 401 response to detect OAuth support per RFC 9728.

​
Option 2: Whitelist Smithery requests

Bot Fight Mode on the free plan cannot be bypassed with WAF custom rules. Your options:
  1. IP Access Rules: Go to Security > WAF > Tools > IP Access Rules and add an Allow rule for Smithery’s IP range
  2. Disable Bot Fight Mode: Go to Security > Bots > Bot Fight Mode and toggle it off (this disables bot protection for all traffic)
  3. Upgrade to Pro: Pro plan ($20/mo) unlocks Super Bot Fight Mode with WAF skip rules (see below)
Create a WAF skip rule to bypass bot protection for Smithery:
  1. Go to Security > WAF > Custom Rules
  2. Create a rule with expression: (http.user_agent contains "SmitheryBot")
  3. Action: Skip > select Super Bot Fight Mode
Add an allow rule for requests matching User-Agent SmitheryBot/1.0. The exact steps vary by provider — consult your CDN/WAF documentation for configuring User-Agent-based allow rules.

​
Option 3: Publish a static server card

Bypass scanning entirely by serving a /.well-known/mcp/server-card.json endpoint on your server. See Static Server Card above.