Deployment - Neo N3 MCP Server

Supported repository paths

Node.js process

Build with npm run build and start HTTP with npm run start:http under an operator-managed process supervisor.

Production Compose

docker/docker-compose.yml builds the production image, requires an API key, persists wallets, and configures health and log limits.

Direct Docker

docker/Dockerfile creates a non-root Node.js 22 Alpine image that runs dist/http.js.

Development Compose

docker/docker-compose.dev.yml bind-mounts source, listens on loopback, and provides a local-only default key.

Production Compose

export HTTP_API_KEY="$(openssl rand -hex 32)"
docker compose -f docker/docker-compose.yml up -d

The API key is required during Compose interpolation.
The container listens on 0.0.0.0:3000.
The host publishes 127.0.0.1:3000 by default.
/app/wallets is persisted in the neo-mcp-wallets volume.
Docker JSON logs are limited to three 10 MiB files.

PORT=8080 HTTP_API_KEY="$HTTP_API_KEY" \
  docker compose -f docker/docker-compose.yml up -d

Registry image

NEO_MCP_IMAGE_REPOSITORY=r3enetwork/neo-n3-mcp \
NEO_MCP_IMAGE_DIGEST=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
HTTP_API_KEY="$HTTP_API_KEY" \
  docker compose -f docker/docker-compose.yml \
    -f docker/docker-compose.registry.yml up -d

Replace the example digest with the release artifact's 64-character lowercase hexadecimal digest. The overlay is digest-only; it does not accept combined image references or mutable tags.

Remote exposure: the container listener is plaintext HTTP and does not terminate TLS. Remote clients must use HTTPS through a TLS-terminating reverse proxy or load balancer. Set HTTP_BIND_ADDRESS=0.0.0.0 only when that proxy must reach the container, and restrict the published port to the proxy.

Direct process

npm ci
npm run build
export HTTP_API_KEY="$(openssl rand -hex 32)"
NEO_NETWORK=mainnet npm run start:http

HTTP requires mainnet or testnet. The default host is loopback. Any configured key must contain at least 32 bytes, and a non-loopback host cannot start without one.

Direct remote plaintext HTTP is unsupported because bearer tokens and WIFs traverse requests. An API key authenticates clients but does not encrypt the connection; keep the backend HTTP hop on loopback or a trusted host-local proxy network.

Security configuration

Variable	Default	Deployment note
`HTTP_HOST`	`127.0.0.1`	Keep loopback unless remote binding is required.
`HTTP_API_KEY`	Unset	Required off loopback; minimum 32 bytes.
`HTTP_CORS_ORIGINS`	Empty	Exact comma-separated origins; no wildcard.
`HTTP_MAX_BODY_BYTES`	1048576	Positive integer request-body limit.
`NEO_TESTNET_RPC`	`https://testnet1.neo.coz.io:443`	Remote RPC endpoints should use HTTPS.
`NEO_RPC_TIMEOUT_MS`	15000	Positive per-attempt RPC deadline in milliseconds.
`NEO_ALLOW_INSECURE_RPC`	false	Explicitly permits remote plaintext HTTP RPC; keep disabled in production.
`NEO_MAX_TRANSACTION_FEE_GAS`	20	Caps combined system and network fees before signing.
`WALLETS_DIR`	`./wallets`	Persist and protect this directory.
`RATE_LIMITING_ENABLED`	Enabled	Process-local; complement it with upstream controls.

Plain HTTP is accepted for loopback RPC endpoints. A remote plaintext HTTP RPC is rejected unless NEO_ALLOW_INSECURE_RPC=true; the override does not encrypt traffic. Signed transactions are rejected before broadcast when combined fees exceed the configured GAS cap.

Health and metrics

curl http://127.0.0.1:3000/live
curl http://127.0.0.1:3000/health

curl -H "Authorization: Bearer $HTTP_API_KEY" \
  http://127.0.0.1:3000/metrics

/live is the unauthenticated process liveness check used by the image. /health is unauthenticated RPC readiness and returns 503 when the selected RPC check fails. /metrics requires the bearer token when a key is configured.

The metrics route emits process uptime, selected-network information, and the latest observed block height in Prometheus text format. No collector, dashboard, alert rules, or metrics storage are included.

CI and publishing boundary

GitHub Actions validates both images and can publish npm and Docker artifacts for a published GitHub release. It does not deploy the image to a host, create cloud resources, configure TLS, route traffic, or automate rollback.

Rollout and rollback

Record the exact npm or image version being deployed and the previous known-good version.
Validate /live and /health before routing traffic.
Validate authenticated /metrics and one read-only API request.
Confirm wallet storage is mounted and writable.
On failure, redeploy the previous artifact and repeat the smoke checks.