deployment guide

Agent Protocol Deployment Guide

Package: @bluefly/agent-protocol v0.1.5 Last Updated: 2026-02-16

Prerequisites

Node.js >= 20.0.0
Docker (for containerized deployment)
kubectl (for Oracle k3s deployment)
GitLab token in ~/.tokens/gitlab
workspace.json on NAS at /Volumes/AgentPlatform/config/workspace.json

Local Development (stdio)

cd worktrees/agent-protocol/release-v0.1.x
npm ci && npm run build
node dist/mcp/server.js

SSE Transport (Development)

MCP_TRANSPORT=sse MCP_PORT=3100 MCP_VERBOSE=true tsx src/mcp/server.ts

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agent-protocol": {
      "command": "node",
      "args": ["/path/to/agent-protocol/dist/mcp/server.js"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Docker Deployment

Build Image

docker build -t agent-protocol-mcp-sse -f infrastructure/Dockerfile.mcp-sse .

Run Standalone

docker run -p 3100:3100 \
  -v /Volumes/AgentPlatform/config/workspace.json:/app/config/workspace.json:ro \
  -v ~/.tokens/:/run/secrets/:ro \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://87749026.otel.gitlab-o11y.com:4318 \
  agent-protocol-mcp-sse

Docker Compose (with Cloudflare tunnel)

docker compose -f infrastructure/docker-compose.mcp-sse.yml up -d

Two services:

mcp-sse: MCP SSE server on port 3100
cloudflared: Cloudflare Tunnel sidecar → mcp.blueflyagents.com

Oracle Cloud k3s Deployment

GitLab CI handles this automatically:

Pipeline builds Docker image tagged with commit SHA
Pushes to GitLab Container Registry
Manual trigger deploys to Oracle k3s namespace bluefly
kubectl sets new image and waits for rollout
Health check on port 3100
OTel deployment trace sent to GitLab

Manual Deployment

kubectl set image deployment/agent-protocol-mcp-sse \
  mcp-sse="registry.gitlab.com/blueflyio/agent-platform/agent-protocol/mcp-sse:$SHA" \
  --namespace=bluefly
kubectl rollout status deployment/agent-protocol-mcp-sse --namespace=bluefly --timeout=300s

CI/CD Pipeline

File: .gitlab-ci.yml Stages: validate → test → build → security → publish → deploy

Job	Stage	Description
typecheck	test	`tsc --noEmit`
unit-test	test	`jest` with junit report
build:mcp-sse	build	Docker build + push to registry
sast	security	GitLab SAST scanning
container_scanning	security	Scans Docker image
dependency_scanning	security	Scans npm dependencies
secret_detection	security	Detects leaked secrets
deploy:mcp-sse:oracle	deploy	Manual trigger to Oracle k3s

CI Components Used:

minimal-ci — Base CI configuration
otel-instrument — OpenTelemetry instrumentation
oracle-deploy — Deploy to Oracle Cloud VM

Health Check

curl http://localhost:3100/health

Response:

{
  "status": "healthy",
  "transport": "sse",
  "tools": 88,
  "activeSessions": 0,
  "otel": {
    "enabled": true,
    "endpoint": "http://87749026.otel.gitlab-o11y.com:4318",
    "serviceName": "agent-protocol"
  },
  "timestamp": "2026-02-16T12:00:00.000Z"
}

Infrastructure Files

File	Description
`infrastructure/Dockerfile.mcp-sse`	Multi-stage Docker build (node:20-alpine, non-root, tini)
`infrastructure/docker-compose.mcp-sse.yml`	MCP SSE + Cloudflare tunnel sidecar
`.gitlab-ci.yml`	Full CI/CD pipeline with GitLab Ultimate security

Public Endpoints

Endpoint	Description
`mcp.blueflyagents.com`	Production MCP SSE server (Cloudflare Tunnel)
`mcp.blueflyagents.com/health`	Health check
`mcp.blueflyagents.com/sse`	SSE connection endpoint

Environment Variables

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport: stdio or sse
`MCP_PORT`	`3100`	SSE server port
`MCP_VERBOSE`	`false`	Verbose logging
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://87749026.otel.gitlab-o11y.com:4318`	OTel collector
`OTEL_SERVICE_NAME`	`agent-protocol`	Service name for traces
`GITLAB_TOKEN`	—	GitLab API token
`LLM_WORKSPACE`	—	Workspace config path

Monitoring

OpenTelemetry traces → GitLab Observability (http://87749026.otel.gitlab-o11y.com:4318)
Every tool call traced: mcp.tool.name, mcp.tool.group, mcp.tool.success, mcp.tool.duration_ms
View traces in GitLab → Monitor → Tracing