Smithery MCP Deployment Best Practices

Documentation Resources

Before implementing MCP features or troubleshooting issues, consult the official MCP specification:

Use the context7 tool to look up current MCP documentation:

• Primary resource: https://context7.com/websites/modelcontextprotocol_io_specification
• This provides the authoritative MCP specification for tools, prompts, resources, and protocol details

Critical: Schema Format (Most Common Issue)

The #1 cause of deployment failures is incorrect schema format. Smithery expects plain objects with Zod properties, NOT z.object() wrappers.

// WRONG - Results in "0/0 tools"
inputSchema: z.object({
  param: z.string()
}).strict()

// CORRECT - Tools will be detected
inputSchema: {
  param: z.string()
}

This applies to:

• inputSchema in tools
• outputSchema in tools
• argsSchema in prompts

Quality Scoring (90/100 Optimal)

| Feature | Points | How to Achieve | |---------|--------|----------------| | Tools with descriptions | 25 | Detailed 2-4 sentence descriptions | | Tool annotations | 20 | Add inside config object (not 4th param) | | Optional config | 15 | All fields optional or with defaults | | Workflow prompts | 15 | Create 3-5 workflow prompts | | Icon | 10 | Add icon.svg to repository root | | Documentation | 5 | Comprehensive README |

Note: "Optional Config" (15pts) and "Config Schema" (10pts) are mutually exclusive. Optional is better UX and higher points.

Tool Registration Template

server.registerTool(
  'tool_name',
  {
    title: 'Action-Oriented Title',
    description: 'Clear 2-4 sentence description. Start with action verb. ' +
                 'Explain behavior (async/blocking). Mention related tools.',
    inputSchema: {
      param: z.string()
        .describe('Specific description with examples (e.g., foo, bar)')
    },
    outputSchema: {
      result: z.string()
    },
    annotations: {              // Inside config object!
      readOnlyHint: true,       // Only reads data?
      destructiveHint: false,   // Deletes/destroys data?
      idempotentHint: true,     // Same input = same result?
      openWorldHint: false      // Deterministic results?
    }
  },
  async (args) => {
    // Args passed directly (not request.params.arguments)
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }
);

Workflow Prompt Template

server.registerPrompt(
  'workflow-name',
  {
    title: 'Workflow Title',
    description: 'End-to-end workflow description',
    argsSchema: {              // Plain object, not z.object()!
      // IMPORTANT: Only z.string() types supported
      param: z.string().describe('Parameter description').optional()
    }
  },
  async (args) => ({
    messages: [{
      role: 'user',
      content: {
        type: 'text',
        text: `Multi-step workflow instructions...`
      }
    }]
  })
);

Configuration Setup

src/types.ts:

export const configSchema = z.object({
  apiToken: z.string().optional()
    .describe("Token (or use API_TOKEN env var)"),
  format: z.enum(["json", "markdown"]).default("markdown")
});

export type Config = z.infer<typeof configSchema>;

src/index.ts:

export { configSchema };  // Must export!

export default function createServer(config?: Config) {
  const server = new McpServer({ name: 'your-server', version: '1.0.0' });
  return server;
}

smithery.yaml (TypeScript runtime):

runtime: "typescript"
# Do NOT include configSchema - auto-detected from TypeScript export

Project Structure

your-mcp-server/
├── icon.svg              <- REQUIRED for 10 points!
├── package.json
├── smithery.yaml
├── tsconfig.json
├── src/
│   ├── index.ts         <- Export createServer & configSchema
│   ├── types.ts         <- Define configSchema
│   ├── tools/           <- Tool implementations
│   ├── prompts/         <- Workflow prompts
│   └── resources/       <- Documentation resources

Testing Before Deployment

# 1. Lint TypeScript
npx tsc --noEmit

# 2. Build with Smithery
npm run build
# Look for: "Config schema: N fields (M required)"

# 3. Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

# 4. Verify in Inspector:
#    - tools/list shows all tools with annotations
#    - prompts/list shows all prompts
#    - Try calling each tool

Common Issues Quick Reference

| Symptom | Cause | Fix | |---------|-------|-----| | "0/0 tools" | Using z.object() | Use plain objects for schemas | | "9/16 parameters" | .optional()/.default() on schema | Remove modifiers, handle in handler | | No annotations | Wrong placement | Put inside config object, not 4th param | | Score stuck at 43 | Schema + annotations | Fix both issues | | Icon not showing | Wrong location | Place icon.svg in repo root | | TS error: request.params | Old handler pattern | Use async (args) => not async (request) => | | TS error: prompt argsSchema | Non-string types | Use only z.string().optional() | | Deployment fails | configSchema in yaml | Remove from yaml for TypeScript runtime |

Detailed Documentation

For comprehensive guides, see:

• Schema Format Details: references/schema-format.md
• Quality Scoring Guide: references/quality-scoring.md
• Troubleshooting: references/troubleshooting.md
• Complete Examples: references/examples.md
• Migration Guide: references/migration.md

Path to 90/100 Checklist

1. Use plain object schemas (not z.object())
2. Remove .optional()/.default() from schemas (handle in handler)
3. Add comprehensive tool descriptions (2-4 sentences)
4. Include annotations in all tools (inside config object)
5. Create 3-5 workflow prompts (use z.string().optional() for args)
6. Add icon.svg to repository root
7. Make all config optional or with defaults
8. Export configSchema from index.ts
9. Remove configSchema from smithery.yaml (for TypeScript)
10. Lint with npx tsc --noEmit before building
11. Test locally with MCP Inspector