random-mcp-server

Minimal remote MCP server packaged for Docker, with Basic Auth and/or API Key auth, plus 3 Python tools:

• generate_poem(topic="life", line_count=4)
• calculate_age(birthdate, as_of=None)
• random_life_advice()

Features

• MCP Streamable HTTP endpoint at /mcp
• Auth on MCP routes (Basic Auth and/or API Key)
• Unauthenticated health check at /health
• One-command deployment via Docker Compose

Enterprise Requirements

For production hosting, security, connectivity, and operations requirements, see docs/server-requirements.md.

Enterprise Security Checklist

For production, apply this minimum security baseline:

1. Put MCP behind an API gateway/WAF with a stable domain (no ngrok).
2. Enforce TLS 1.2+ and redirect HTTP to HTTPS.
3. Use strong auth (OIDC/JWT or mTLS preferred); keep API key only if required.
4. If API keys are used, issue per-client keys and rotate via secret manager.
5. Keep the MCP service private; expose only gateway/ingress.
6. Apply network controls (NetworkPolicy, security groups, egress allowlist).
7. Store secrets in a managed store (not in repo, not in plain YAML).
8. Enforce request limits (rate, size, timeout, concurrency).
9. Log/audit tool calls with identity and latency, but never log secrets/PII.
10. Use scanned/signed images, progressive rollouts, and tested rollback runbooks.

Quick Start

1. Create your environment file:

cp .env.example .env

2. Edit .env and set secure credentials:

MCP_BASIC_AUTH_USERNAME=admin
MCP_BASIC_AUTH_PASSWORD=change-me
MCP_API_KEY_LOCATION=header
MCP_API_KEY_PARAMETER_NAME=x-api-key
MCP_API_KEY_VALUE=replace-with-strong-api-key

At least one auth method must be configured:

• Basic Auth (MCP_BASIC_AUTH_USERNAME + MCP_BASIC_AUTH_PASSWORD)
• API Key (MCP_API_KEY_VALUE)

3. Build and run:

docker compose up --build -d

4. Verify health:

curl http://localhost:8000/health

Expected response:

{"status":"ok"}

MCP Endpoint

• URL: http://localhost:8000/mcp
• Auth: Basic Auth and/or API Key (from .env)

Example request without auth (should return 401):

curl -i http://localhost:8000/mcp

Example MCP request with Basic Auth:

curl -i -u "$MCP_BASIC_AUTH_USERNAME:$MCP_BASIC_AUTH_PASSWORD" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://localhost:8000/mcp

Example MCP request with API Key header:

curl -i \
  -H "${MCP_API_KEY_PARAMETER_NAME}: ${MCP_API_KEY_VALUE}" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://localhost:8000/mcp

MCP Inspector (Quick Check)

If you use MCP Inspector, configure:

• Transport: Streamable HTTP
• URL: http://localhost:8000/mcp
• Headers:
  • Authorization: Basic <base64(username:password)> (Basic Auth), or
  • ${MCP_API_KEY_PARAMETER_NAME}: ${MCP_API_KEY_VALUE} (API Key)

Generate the header value:

printf '%s' "$MCP_BASIC_AUTH_USERNAME:$MCP_BASIC_AUTH_PASSWORD" | base64

Run Tests

python -m pytest -q

Kubernetes Deployment Option

You can deploy this MCP server to Kubernetes using the manifests in k8s/.

1. Build and push your image:

docker build -t ghcr.io/<your-org>/random-mcp-server:<tag> .
docker push ghcr.io/<your-org>/random-mcp-server:<tag>

2. Update image in k8s/deployment.yaml:

image: ghcr.io/<your-org>/random-mcp-server:<tag>

3. Create your secrets (recommended via secret manager/CI, not committed files):

kubectl create secret generic random-mcp-secrets \
  --from-literal=MCP_BASIC_AUTH_USERNAME=<username> \
  --from-literal=MCP_BASIC_AUTH_PASSWORD=<password> \
  --from-literal=MCP_API_KEY_LOCATION=header \
  --from-literal=MCP_API_KEY_PARAMETER_NAME=x-api-key \
  --from-literal=MCP_API_KEY_VALUE=<strong-api-key>

4. Deploy:

kubectl apply -k k8s

5. Optional ingress:

kubectl apply -f k8s/ingress.example.yaml

Use your ingress domain + /mcp as the MCP URL.

In-Cluster Access (k8s1 -> k8s1)

If your clients run in the same Kubernetes cluster, do not use ngrok/ingress. Use the internal service DNS directly:

• http://random-mcp.<namespace>.svc.cluster.local:8093/mcp

Example (API key auth):

curl -sS \
  -H "x-api-key: <your-api-key>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://random-mcp.<namespace>.svc.cluster.local:8093/mcp

You can also run the included client pod example:

kubectl apply -f k8s/in-cluster-client.example.yaml
kubectl logs random-mcp-client-test
kubectl delete pod random-mcp-client-test

AWS SAM Cloud MCP Config

For SAM Cloud MCP integration, use:

• Protocol: Streamable HTTP
• URL: your public tunnel/domain + /mcp
• Authentication Type: API Key
• API Key Location: Header
• API Key Parameter Name: value from MCP_API_KEY_PARAMETER_NAME
• API Key Value: value from MCP_API_KEY_VALUE

If using ngrok free tunnels and your client is blocked by ngrok warning pages, add:

• ngrok-skip-browser-warning: 1

Notes

• TLS is intentionally out of scope in this container. For production, place this service behind HTTPS termination (reverse proxy / ingress).
• /health is intentionally open for orchestration and uptime checks.
• .env is ignored by git; keep real credentials there and never commit them.