MCP Server Configuration

The MCP server is configured entirely through environment variables, following the Twelve-Factor App methodology. Every setting has a sensible default except PROXIMA_API_URL, which is required.

Environment Variables

Variable	Default	Required	Description
PROXIMA_API_URL	—	Yes	Proxima Backend base URL (e.g. http://localhost:8080)
PROXIMA_MCP_LISTEN_ADDR	127.0.0.1:8081	No	HTTP listen address. Binds to localhost by default (intended to sit behind the nginx reverse proxy); set 0.0.0.0:8081 to listen on all interfaces
PROXIMA_MCP_TLS_CERT	—	No	TLS certificate file path
PROXIMA_MCP_TLS_KEY	—	No	TLS private key file path
PROXIMA_MCP_AUTH_CACHE_TTL	60s	No	Auth validation cache TTL (Go duration)
PROXIMA_MCP_MAX_RESPONSE_TOKENS	4000	No	Hard cap on tokens per tool response
PROXIMA_MCP_RATE_LIMIT	60	No	Max requests per API key per minute (0 = disabled)
PROXIMA_MCP_TRANSPORT	http	No	Transport: http or stdio
PROXIMA_LOG_LEVEL	info	No	Log level: debug, info, warn, error
PROXIMA_MCP_OTEL_ENABLED	false	No	Enable OpenTelemetry tracing
PROXIMA_MCP_OTEL_ENDPOINT	localhost:4317	No	OTLP gRPC exporter endpoint
PROXIMA_API_KEY	—	No	API key for stdio transport (injected into context)

stdio transport

When PROXIMA_MCP_TRANSPORT=stdio, the server reads MCP messages from stdin and writes to stdout. The PROXIMA_API_KEY environment variable is used for authentication since there is no HTTP header. The HTTP listener, /healthz, and /metrics endpoints are not started in stdio mode.

Deployment

Production runs on Kubernetes

Production deploys to Kubernetes via ArgoCD GitOps (alongside the rest of the Proxima Console stack). The systemd-managed Docker setup below is the legacy / self-host path; the container image and environment variables it uses are still valid and apply to either topology.

In the self-host model the MCP server runs as a Docker container managed by systemd, following the same pattern as the Proxima Backend.

systemd Unit

The systemd unit file is at infra/deploy/systemd/proxima-mcp.service:

[Unit]
Description=Proxima MCP Server (Docker)
After=docker.service
Requires=docker.service

[Service]
Type=simple
EnvironmentFile=/opt/proxima/.env
ExecStartPre=-/usr/bin/docker rm -f proxima-mcp
ExecStart=/usr/bin/docker run --rm --name proxima-mcp \
    --network host \
    --env-file /opt/proxima/.env \
    registry.prxm.uz/proxima/console/mcp:IMAGE_TAG
ExecStop=/usr/bin/docker stop proxima-mcp
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

The IMAGE_TAG placeholder is replaced with the actual commit SHA during deployment by scripts/deploy-dev.sh.

Docker Image

The Dockerfile at infra/docker/mcp/Dockerfile uses a multi-stage build:

1. Builder stage — golang:1.26.4-alpine, compiles the binary with -ldflags="-s -w" for a smaller image
2. Runtime stage — alpine:3.22, runs as non-root proxima user, healthcheck on /healthz

Build manually:

docker build -f infra/docker/mcp/Dockerfile -t proxima-mcp .

nginx Reverse Proxy

The MCP server is exposed externally via nginx at mcp-console.prxm.uz. The vhost config is at infra/deploy/nginx/mcp-console.prxm.uz.conf:

server {
    listen 80;
    server_name mcp-console.prxm.uz;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Makefile Targets

Target	Description
make build-mcp	Build the MCP server binary to bin/proxima-mcp
make run-mcp	Run the MCP server locally via go run
make test-coverage-mcp	Run MCP tests with coverage (MCP tests also run as part of make test)
make coverage-check-mcp	Run tests with 70% coverage enforcement
make lint-go	Lint all Go code including MCP (via golangci-lint)

Local Development

# Start the MCP server locally (requires backend running on :8080)
PROXIMA_API_URL=http://localhost:8080 make run-mcp

# Or run in stdio mode for testing with an MCP client
PROXIMA_API_URL=http://localhost:8080 \
  PROXIMA_MCP_TRANSPORT=stdio \
  PROXIMA_API_KEY=your_api_key \
  go run ./mcp/cmd/mcp

# Build the binary
make build-mcp

# Run tests
cd mcp && go test ./... -race

Auth Cache

The MCP server caches API key validation results to avoid calling the backend's GET /api/v1/auth/validate endpoint on every tool call. The cache is keyed by the SHA-256 hash of the API key (plaintext keys are never stored or logged).

• Default TTL: 60 seconds
• Cache eviction: Entries expire after TTL; no background cleanup (lazy eviction on next access)
• Concurrent safety: Protected by sync.RWMutex (read lock for cache hits, write lock for updates)

Tune PROXIMA_MCP_AUTH_CACHE_TTL based on your needs:

• Lower TTL (10-30s): More frequent backend auth calls, faster permission revocation
• Higher TTL (5-10m): Fewer backend calls, longer delay before permission changes take effect

Token Limits

The PROXIMA_MCP_MAX_RESPONSE_TOKENS setting controls the maximum size of tool responses. Responses exceeding this limit are truncated with a [truncated] marker. This prevents large query results from overwhelming the LLM's context window.

• Default: 4000 tokens (~16,000 characters)
• Increase for tools that return large datasets (e.g. search_logs with high limits)
• Decrease if your LLM client has a small context window