Configuration

Required Files

There are two files required in your repository in order to deploy:

1. Dockerfile
2. smithery.yaml

The Dockerfile tells us how to build your server. The smithery.yaml file tells us how to start your server.

Automatic Setup

Smithery will try to automatically generate a pull-request with these files for you when you trigger a deployment. However, in some cases, the setup can fail and you may need to set this up manually.

Manual Setup

Dockerfile

Create a Dockerfile in your repository root that defines how to build your MCP server. Your Dockerfile should be created such that running your Docker image will start your STDIO server.

Here's an example Dockerfile that builds a Node-based MCP server:

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy application code
COPY . .

# Build the application
RUN npm run build

# Command will be provided by smithery.yaml
CMD ["node", "dist/index.js"]

We only support Linux Docker images on major distros (Alpine/Debian-based) and expect sh to run in your container. Other distros are untested and may not deploy.

For examples, see llms.txt.

You can find more examples of Dockerfiles in Smithery's reference implementations.

smithery.yaml

Create a smithery.yaml file in your repository root. This file defines how your MCP server should be started.

Here's a minimal example of a server with no configuration options:

# Smithery.ai configuration
startCommand:
type: stdio
configSchema:
  # JSON Schema defining the configuration options for the MCP.
  {}
commandFunction:
  # A function that produces the CLI command to start the MCP on stdio.
  |-
  (config) => ({
    "command": "node",
    "args": [
      "dist/index.js"
    ],
    "env": {
      ...
    }
  })

The startCommand object consists of:

• type: stdio: Specifies that your repository is a standard I/O based MCP server
• configSchema: Defines the JSON Schema for your server's configuration options. Users will configure this your server using this schema. We will reject invalid configurations.
• commandFunction: A JavaScript function that returns the command, arguments and environment variables required to start your server. This function is run within your server's sandbox during runtime to parse the config specified by clients. You can trust that config input argument conforms to your configSchema.

Optional configuration:

• build: Object containing build configuration:
  • dockerfile (optional): Path to Dockerfile, relative to this config file
  • dockerBuildPath (optional): Path to docker build context, relative to this config file

For examples, see llms.txt.

Subdirectories

If your package is not in the root directory of your repository (in the case of a monorepo), you should place your Dockerfile and smithery.yaml in the subdirectory that contains your package. You will need to specify the base directory in your server settings on Smithery.

For example, if your MCP server is in the packages/mcp-server directory, you would:

1. Place your Dockerfile and smithery.yaml in the packages/mcp-server directory
2. Set the base directory to packages/mcp-server in your server settings under Github integration

Best Practices

1. Testing: Test your MCP server locally before deploying using MCP Inspector. Please ensure your Dockerfile builds locally first before deploying.
2. Configuration: Use the configSchema to properly define and validate your server's configuration options
3. Docker Optimization: Keep your Docker image size minimal by using appropriate base images and multi-stage builds