Docker publishing

For easier distribution and deployment, you can publish Docker images for your MCP server. This creates a containerized version that can be easily deployed and distributed.

Configure Docker publishing

Under the TypeScript target in your Stainless config, add the mcp_server.publish.docker option:

targets:
  typescript:
    options:
      mcp_server:
        publish:
          docker: myorg/my-api-mcp

Your Docker image is published to Docker Hub by default. To use a different registry:

targets:
  typescript:
    options:
      mcp_server:
        publish:
          docker:
            image_name: myorg/my-api-mcp
            registry: ghcr.io

Create a Docker Hub access token

You can create either a Personal Access Token or an Organization Access Token depending on your setup.

Use this for individual Docker Hub accounts or when you don’t have a Docker Team/Business subscription:

1. Sign in to your Docker Hub account at hub.docker.com
2. Navigate to Account Settings > Security > Personal Access Tokens
3. Click Generate new token
4. Provide a descriptive token name (e.g., “MCP Server GitHub Actions Publishing”)
5. Set access permissions to Read & Write (required for pushing images)
6. Click Generate and immediately copy the token

For more details, see Docker’s Personal Access Token documentation.

Use this if you have a Docker Team or Business subscription and want centralized token management:

1. Sign in to Docker Hub and navigate to the Admin Console
2. Select your organization
3. Go to Access tokens > Generate token
4. Configure:
   • Label and description: “MCP Server GitHub Actions Publishing”
   • Expiration date: Set appropriate expiration
   • Repository access: Select repositories this token can access
   • Access permissions: Enable Read & Write
5. Generate and immediately copy the token

Organization Access Tokens provide better security and management features but are incompatible with Docker Desktop. For more details, see Docker’s Organization Access Token documentation.

Treat access tokens like passwords. Store the token securely—you won’t be able to see it again after creation.

Add credentials to your production repo

1. Open your production repo in GitHub
2. Navigate to Settings > Secrets and variables > Actions > New repository secret
3. Add a DOCKERHUB_TOKEN secret with your access token as the value
4. Navigate to Settings > Secrets and variables > Actions > Variables tab > New repository variable
5. Add a DOCKERHUB_USERNAME variable:
   • For personal access tokens: use your Docker Hub username
   • For organization access tokens: use the organization name

Publish to Docker Hub

After Docker publishing is configured, the next build generates the necessary Docker assets (Dockerfile, .dockerignore, bin/docker-tags script, and a GitHub Actions workflow) in your SDK.

Versioning follows the same strategy as npm publishing, with exact version tags, latest for stable releases, and pre-release tags like alpha or beta when appropriate. See versioning and releases for details.

Your Docker image is published automatically when a release PR is merged. You can also run the GitHub workflow manually.

Use published Docker images

Once published, users can run your MCP server using Docker:

# Pull and run the latest version
docker run --rm -i myorg/my-api-mcp

# Run a specific version
docker run --rm -i myorg/my-api-mcp:1.2.3

# With environment variables
docker run --rm -i -e MY_API_KEY=your-api-key myorg/my-api-mcp

For remote deployment with HTTP transport, see Remote deployment.