Skip to main content

Deploying HAPI MCP Server on Cloudflare Workers

This guide explains how to deploy the HAPI MCP Server to Cloudflare Workers using the HAPI MCP CLI (hapi deploy). This approach leverages the built-in deployment command and does not require you to write your own worker code or configuration from scratch.

Prerequisites​

Steps​

1. Authenticate with Cloudflare​

Ensure you are authenticated with Cloudflare:

wrangler whoami

If not authenticated, log in:

wrangler login

Or, if using the HAPI MCP CLI:

hapi login

2. Deploy to Cloudflare Workers​

The HAPI MCP CLI provides a deploy command that deploys the HAPI MCP Server as a Cloudflare Worker. The minimum required option is the OpenAPI spec URL.

Basic example:

hapi deploy --specs https://petstore3.swagger.io/api/v3/openapi.json

With backend URL and custom worker name:

hapi deploy --specs https://petstore3.swagger.io/api/v3/openapi.json \
  --url https://petstore3.swagger.io/api/v3 \
  --name my-hapi-worker

With extra environment variables:

hapi deploy --specs <OPENAPI_URL> --var API_KEY=your-key --var DEBUG=true

Key Options​

  • --specs <url>: (Required) URL or path to your OpenAPI spec. --openapi still works as a legacy alias, but new scripts should use --specs.
  • --url <url>: (Optional) Backend base URL for headless mode.
  • --public-host <host>: (Optional) The public URL clients will use to reach this Worker (e.g. https://api.example.com). Required whenever the deployed server advertises OAuth/MCP resource metadata, since that metadata must point at a URL clients can actually reach.
  • --name <name>: (Optional) Custom worker name (must be RFC 1123 compliant).
  • --project <project>: (Optional) Project name for grouping deployments.
  • --var <key=value>: (Optional, repeatable) Extra environment variables.
  • --dry-run: (Optional) Print actions without executing.
OAuth-protected specs require an Enterprise license

Deploying a document whose security scheme requires HAPI's interactive OAuth broker (for example, passing --tokens-db for a production D1-backed Worker) needs the licensed @mcp-com-ai/enterprise-plugin-auth plugin and a core.enterprise/auth.oauth-broker entitlement. Static API-key, Basic, and Bearer auth deploy on the free OSS CLI with no license needed. See Authentication & Licensing for details.

Example output:

📝 Generating temporary Wrangler config...
⚙️ Deploying to Cloudflare Workers...
🌍 Live at: https://my-hapi-worker.your-account.workers.dev
✅ Deployed successfully!

3. (Optional) Advanced Usage​

  • Dry Run: See what would be deployed without making changes:

    hapi deploy --specs <OPENAPI_URL> --dry-run

  • Keep Config: Retain the generated worker files for inspection:

    hapi deploy --specs <OPENAPI_URL> --keep-config

  • Custom Project Name: Useful for grouping or CI/CD:

    hapi deploy --specs <OPENAPI_URL> --project my-hapi-project

4. Monitor and Manage Your Worker​

Notes​

  • The worker name must be unique, start with a letter, and use only lowercase letters, numbers, and hyphens.
  • The CLI will attempt to generate a valid name if not provided.
  • For sensitive data, use Cloudflare secrets.
  • The deployment process will clean up temporary files unless --keep-config is specified.

Example: Full Command​

hapi deploy --specs https://petstore3.swagger.io/api/v3/openapi.json \
  --url https://petstore3.swagger.io/api/v3 \
  --name petstore-hapi \
  --var API_KEY=your-key

References​