Skip to main content

Deploying HAPI MCP Server on Fly.io

This guide explains how to deploy the HAPI MCP Server on Fly.io using the official pre-built image (hapimcp/hapi-cli). You do not need to build or customize a Dockerfile—just use the official image for a fast, reliable deployment.

Prerequisites​

Quick Start: Run a HAPI MCP Server Instantly​

For rapid prototyping or testing, you can use fly machine run to launch a HAPI MCP Server instance immediately, bypassing the need for manual app creation or configuration files.

fly machine run hapimcp/hapi-cli:latest --command \
  "hapi serve --specs https://petstore3.swagger.io/api/v3/openapi.json --url https://petstore3.swagger.io/api/v3 --headless"
  • Replace latest with a specific version tag if needed.
  • Pass hapi serve's own flags (--specs, --url, --headless, etc.) directly in --command — this is the same invocation you'd run locally, just wrapped for Fly's machine runner.
  • Use -e to set additional environment variables the server should see at runtime (e.g. HAPI_PUBLIC_HOST, secrets), not the document source itself.

Possible Combinations

  • Custom Port: Add -p 8080 to expose a specific port.

  • Additional Environment Variables: Add more -e VAR=value flags as needed.

  • Custom Command: Run a different command if you need to override the default entrypoint.

Ephemeral Machines:​

Add --ephemeral to create a machine that is automatically destroyed when stopped.

Recommended: Launch and Deploy for Production

If you plan to run a production MCP server, follow the full deployment steps below to create a persistent app with proper configuration that can be managed and scaled.

Steps​

1. Authenticate with Fly.io​

Log in to your Fly.io account:

fly auth login

If you don't have an account, sign up with:

fly auth signup

2. Create and Configure Your App/MCP Server​

Create a new Fly.io app and generate a configuration file:

fly launch --no-deploy --image hapimcp/hapi-cli:latest
  • When prompted, choose a unique app name and region.
  • This creates a fly.toml file in your directory. Add a [processes] entry telling Fly which hapi serve command to run — see the fly.toml example at the end of this guide, which passes --specs/--url/--headless directly rather than through environment variables.

3. Edit fly.toml for the Pre-Built Image​

Open the generated fly.toml and ensure it does not reference a build section. You will deploy using the pre-built image, so the build section can be removed or ignored.

4. Deploy the Pre-Built HAPI MCP Image​

Deploy your app using the official image:

fly deploy -- serve
# Or specify the image explicitly:
fly deploy --image hapimcp/hapi-cli:latest
  • Replace latest with a specific version tag if needed.
  • This command will push the pre-built image to Fly.io and start your HAPI MCP Server.

5. (Optional) Set Environment Variables​

If your HAPI MCP Server requires environment variables, set them with:

fly secrets set VAR_NAME=value

Or add them to your fly.toml under the [env] section.

warning

Use secrets for sensitive data like API keys.

6. Monitor and Access Your App/MCP Server​

After deployment, Fly.io will provide a public URL for your app. You can monitor logs with:

fly logs

Notes​

  • No Dockerfile or local build is required.
  • You can redeploy at any time with the same fly deploy --image ... command.
  • For advanced configuration (volumes, scaling, etc.), refer to the Fly.io documentation.

fly.toml example for HAPI MCP Server​

app = 'my-mcp-server'
primary_region = 'dfw'

[build]
  image = 'hapimcp/hapi-cli:latest'

[processes]
  app = 'hapi serve --specs https://petstore3.swagger.io/api/v3/openapi.json --url https://petstore3.swagger.io/api/v3 --headless'

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 0
  processes = ['app']

[[vm]]
  memory = '256mb'
  cpus = 1
  memory_mb = 256
note

internal_port matches hapi serve's default port (3000). If you pass --port explicitly, update internal_port to match.