Skip to main content

Deploy Docker-based hosted connectors

Package your MCP server in a Docker image and deploy it to MintMCP's hosted infrastructure. MintMCP runs the container, handles scaling, and manages the connection for your organization.

Three ways to deploy​

MethodBest for
Claude Code skillGuided workflow — Claude helps you build the Dockerfile, test locally, and deploy
hosted-cli directlyYou already have a working Dockerfile and want to deploy from the command line
Connector admin UIYou have a pre-built image in a registry and want to configure it in the MintMCP web UI

Using the Claude Code skill​

Install the hosted-deploy plugin in Claude Code:

/plugin marketplace add mintmcp/mintmcp-claude-code
/plugin install hosted-deploy@mintmcp-claude-code

Then ask Claude to deploy your server:

  • "Deploy this MCP server to MintMCP as a hosted connector"
  • "Create a Dockerfile for my FastMCP server to deploy on MintMCP"
  • "Help me deploy my MCP server using hosted-cli"

Claude walks you through the decision tree (transport, credentials, OAuth), builds a Dockerfile if needed, tests locally, and deploys.

Requirements​

  • Transport: HTTP streamable preferred. The server must serve at /mcp on port 8000. stdio is supported but slower — only use it if the server exclusively supports stdio.
  • Self-contained image: All dependencies baked into the Docker image.
  • Image size: Under 1 GB (under 250 MB recommended).
  • Platform: linux/amd64.
  • Credentials at startup: The server should start and respond to initialize and tools/list without requiring user credentials. Credentials are only available at request time, not at container startup.

Deploying manually with hosted-cli​

Prerequisites​

  • Docker installed and running
  • Node.js 18+ (for npx)
  • A Dockerfile that meets the requirements above

Authenticate​

npx @mintmcp/hosted-cli auth login

Test locally​

npx @mintmcp/hosted-cli test-image --dockerfile Dockerfile --context .

This builds the image, starts it, and verifies it responds to MCP requests.

Deploy​

New connector:

npx @mintmcp/hosted-cli build-and-push \
  --name "My Connector" \
  --transport http \
  --dockerfile Dockerfile \
  --context .

Update an existing connector (from the same directory with .mintmcp/hosted.json):

npx @mintmcp/hosted-cli build-and-push \
  --dockerfile Dockerfile \
  --context .

Deploy a pre-built image from a registry:

npx @mintmcp/hosted-cli deploy \
  -n "My Connector" \
  --image ghcr.io/org/my-server:latest \
  -t http

The CLI prints a connector settings URL where you can view logs, configure environment variables, and manage revisions.

Configuring an image in the connector admin UI​

If your image is already published to a registry (Docker Hub, GHCR, etc.), you can configure it directly in the MintMCP web UI without using the CLI.

  1. Open your MCP gateway in the MCP store and go to the connector settings for your hosted connector.
  2. Under Container Image, enter your image reference. Pin to a digest for reproducibility (e.g., org/my-server@sha256:abc123...).
  3. Set the Transport to HTTP or stdio.
  4. If the server needs a startup command, enter it in the Command field. For HTTP images that use their own entrypoint, leave this blank.
  5. Configure environment variables as needed.
  6. Save — MintMCP pulls the image, starts the container, and runs health checks.

Credentials and environment variables​

After deploying, configure environment variables at the connector settings URL.

Credential typeHow to configure
No credentialsNothing to do
Shared API keySet as a global environment variable in the connector settings
Per-user API keysSet as a per-user environment variable — each user is prompted for their value on first connection
OAuthConfigure OAuth settings (authorization URL, token URL, scopes, client credentials) in the connector settings after deployment. MintMCP handles the OAuth flow and forwards fresh access tokens to the server as a header (HTTP) or env var (stdio). The server just needs to accept the token — no OAuth implementation needed in the server itself.

For HTTP transport, per-user credentials and OAuth tokens are forwarded as request headers. For stdio, they're injected as environment variables automatically.

Next steps​