Skip to main content
This Python quickstart is currently in beta. Run into any issues? Reach us at our Discord.
Get started with one command: 
uvx smithery init

​
Overview

In this quickstart, we’ll build a simple MCP server that says hello to users. We’ll use the official Python MCP SDK with the Smithery CLI. By the end, you’ll have a live, deployed server with built-in authentication that you can connect to from any MCP client. For TypeScript, check out our TypeScript quickstart guide.

​
Prerequisites

​
1. Initialize the Server

uvx smithery init
This sets up a Python MCP server scaffold with example code and all necessary dependencies.

​
2. Edit the Server

In src/hello_server/server.py, you’ll see a default server that says hello to a given name. Edit it to add your own tools, resources, and prompts. Here’s the basic structure: 
from pydantic import BaseModel, Field
from mcp.server.fastmcp import Context, FastMCP

from smithery.decorators import smithery 

# Optional: Configuration schema for session
class ConfigSchema(BaseModel):
    pirate_mode: bool = Field(False, description="Speak like a pirate")

@smithery.server(config_schema=ConfigSchema) 
def create_server(): 
    """Create and configure the MCP server."""
    
    # Create your FastMCP server as usual
    server = FastMCP("Say Hello")

    # Add a tool
    @server.tool()
    def hello(name: str, ctx: Context) -> str:
        """Say hello to someone."""
        # Access session-specific config through context
        session_config = ctx.session_config
        
        # Create greeting based on pirate mode
        if session_config.pirate_mode: 
            return f"Ahoy, {name}!"
        else: 
            return f"Hello, {name}!"

    # The scaffold also includes example resources and prompts
    # @server.resource("example://resource")
    # @server.prompt()

    return server
Adding config schema (optional)Smithery allows users to customize server behavior for each session by providing API keys, adjusting settings, or modifying operational parameters. Optionally define a ConfigSchema using Pydantic to specify what configuration your server accepts:
class ConfigSchema(BaseModel):
    api_key: str = Field(..., description="Weather API key")
    unit: str = Field("celsius", description="Temperature unit preference")

@smithery.server(config_schema=ConfigSchema)
def create_server():
    # Access config via ctx.session_config in your tools
No config needed? Just omit the config_schema parameter: @smithery.server()

​
3. Testing the Server

For local development: 
uv run dev
This launches your server locally for development and testing. For testing in the Smithery Playground: 
uv run playground
This will port-forward your local server to the Smithery Playground via ngrok. You can now test your server by prompting something like “Say hello to Henry”.

​
4. Deploy the Server

Deployment is a one-click process. Just make a GitHub repo, push your local changes, and then click “Deploy” on the Smithery home page.

​
Good to Know

The @smithery.server() decorator enhances any FastMCP server with deployment features:
# You create FastMCP as usual
server = FastMCP("My Server")

@server.tool()
def my_tool(arg: str, ctx: Context) -> str:
    # Access session-specific config via context
    config = ctx.session_config
    return f"Hello {arg}!"
Smithery adds:
  • Session-scoped configuration management
  • CORS headers for web client compatibility
  • Runtime patches for deployment environment
You write normal FastMCP code, and Smithery automatically enhances it for production deployment. Each session gets its own config, enabling per-user customization.
The scaffold creates a pyproject.toml file with this configuration:
[tool.smithery]
server = "hello_server.server:create_server"
This tells Smithery exactly where to find your server function using Python’s import syntax: module.path:function_name. The @smithery.server() decorator then provides all the configuration metadata (config schema, server name, etc.).
⌘I