Private HTTP deployment

This page is for an always-on Streamable HTTP server. Local desktop clients should use their standard STDIO recipe. ChatGPT web uses Secure MCP Tunnel instead; it is outbound-only and does not need this HTTP bearer-key deployment.

Generate and retain the HTTP key

Generate the bearer key once in a shell with a secret manager or service manager behind it:

FLUENTCART_HTTP_KEY="$(openssl rand -hex 32)"

Store that exact value in the deployment secret manager and configure the same value in the HTTP client. Do not regenerate it inside docker run: a client cannot authenticate to a key that was created and immediately discarded. Do not commit the value, either. It is not a decorative string.

Docker image

The images are published for linux/amd64. The container starts HTTP transport on port 3000. Bind the host port to loopback when the reverse proxy or tunnel is on the same host:

docker run -d \
  -p 127.0.0.1:3000:3000 \
  -e FLUENTCART_URL=https://your-store.com \
  -e FLUENTCART_USERNAME=fluentcart-reader \
  -e FLUENTCART_APP_PASSWORD="read from your deployment secret manager" \
  -e FLUENTCART_MCP_API_KEY=$FLUENTCART_HTTP_KEY \
  -e FLUENTCART_MCP_ALLOWED_HOSTS=mcp.your-domain.com \
  -e FLUENTCART_MCP_ALLOWED_ORIGINS=mcp.your-domain.com \
  --name fluentcart-mcp \
  vcodesh/fluentcart-mcp

The same-host endpoint is http://127.0.0.1:3000/mcp; terminate TLS at a trusted proxy or tunnel before giving clients the public https:// address.

Required environment

Variable	Required	Description
`FLUENTCART_URL`	Yes	WordPress site root
`FLUENTCART_USERNAME`	Yes	Least-privilege WordPress principal
`FLUENTCART_APP_PASSWORD`	Yes	Its Application Password from a secret manager
`FLUENTCART_MCP_API_KEY`	Yes, for private HTTP	Bearer token, at least 32 characters
`FLUENTCART_MCP_ALLOWED_HOSTS`	Yes, for private HTTP	Comma-separated allowed Host names
`FLUENTCART_MCP_ALLOWED_ORIGINS`	Yes, for private HTTP	Comma-separated allowed browser Origin names
`FLUENTCART_WRITE_MODE`	No	`disabled` by default or explicitly `reversible`
`FLUENTCART_TIMEOUT`	No	Request timeout in milliseconds; default 30000

Binding and authentication

The HTTP transport itself binds 127.0.0.1 by default. The Docker entry point binds inside the container, while -p 127.0.0.1:3000:3000 keeps the host listener loopback-only. A non-loopback private profile refuses to listen without a 32-character-or-longer bearer key and both Host and Origin allowlists. These checks happen before listening.

Every /mcp request needs Authorization: Bearer <key>. Missing, malformed, and wrong keys all return the same {"error":"Unauthorized"} response and use a constant-time comparison.

One bearer key is one transport principal

The token maps to one configured WordPress principal. There is no OAuth or multi-user identity mapping. Run separate processes when callers require different WordPress roles; routing a single token through a proxy does not turn it into identity management.

The bearer key guards endpoint access. It does not change what FluentCart MCP can do: FLUENTCART_WRITE_MODE still defaults to disabled, and the WordPress user still bounds available routes. Refunds and subscription cancellation are absent, as are deletion, bulk mutations, order-status changes, marking an order paid, and dispute handling.

Dokploy

Create a Docker Image application

Use vcodesh/fluentcart-mcp:latest, or use Git with build context fluentcart-mcp/.

Add deployment secrets and allowlists

Set the three WordPress values, the retained FLUENTCART_MCP_API_KEY, and both allowlists through Dokploy secrets. Set the allowlists to the public hostname exposed by Dokploy, the reverse proxy, or the tunnel.

Expose only the intended path

Route port 3000 through Dokploy’s TLS proxy and configure the MCP client with the HTTPS /mcp URL and the same retained bearer token.

Cloudflare Tunnel or a same-host reverse proxy

For Cloudflare Tunnel, create a public hostname such as mcp.your-domain.com, then point the service at http://127.0.0.1:3000. For a same-host reverse proxy, upstream to the same loopback address. In both cases keep the Docker port mapping as 127.0.0.1:3000:3000, terminate valid TLS at the public edge, and set both allowlists to mcp.your-domain.com.

The externally configured MCP URL is then https://mcp.your-domain.com/mcp; keep its bearer token in that client’s secret configuration. The tunnel or proxy does not replace bearer authentication.

Health and HTTP clients

Check liveness without a bearer token:

curl https://mcp.your-domain.com/health

It returns {"status":"ok"} when the process is alive. /health says nothing about store access; /mcp remains bearer-protected. For failures, inspect:

docker logs fluentcart-mcp

Point an MCP client that supports Streamable HTTP at the /mcp URL and configure the retained bearer token in that client’s authentication field. The HTTP transport creates a fresh server per request, which suits scale-to-zero deployments but rebuilds the filtered registry each time.

Docker Compose

Put secrets in an ignored .env or the deployment secret manager, then reference them rather than embedding them in source:

docker-compose.yml

services:
  fluentcart-mcp:
    image: vcodesh/fluentcart-mcp:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      FLUENTCART_URL: ${FLUENTCART_URL}
      FLUENTCART_USERNAME: ${FLUENTCART_USERNAME}
      FLUENTCART_APP_PASSWORD: ${FLUENTCART_APP_PASSWORD}
      FLUENTCART_MCP_API_KEY: ${FLUENTCART_HTTP_KEY}
      FLUENTCART_MCP_ALLOWED_HOSTS: mcp.your-domain.com
      FLUENTCART_MCP_ALLOWED_ORIGINS: mcp.your-domain.com
    restart: unless-stopped

Create FLUENTCART_HTTP_KEY with the command above, retain it in the deployment secret manager, configure the same value in the HTTP client, and then run docker compose up -d.

Private HTTP deployment

On this page