Agent Protocol MCP Server

Package: @bluefly/agent-protocol v0.1.5 Last Updated: 2026-02-17 Status: Production Source: GitLab

---

Table of Contents

1. Overview
2. Architecture
3. Tool Reference (88 Tools)
4. SSE Transport
5. OpenTelemetry Integration
6. Config Resolution System
7. Deployment
8. Running Locally
9. Environment Variables
10. MCP Resources
11. Related Documentation

---

Overview

The Agent Protocol MCP Server is the central Model Context Protocol server for the BlueFly.io infrastructure. It is a single server that exposes the entire platform through the MCP standard, making all capabilities available to MCP-compatible clients such as Claude Desktop, Cursor IDE, and custom integrations.

Key Characteristics

• SDK-native: Built on @modelcontextprotocol/sdk v1.26.0 -- no custom HTTP framework, no Express
• Dual transport: stdio for local development (Claude Desktop, CLI) and SSE for remote deployment at mcp.blueflyagents.com via Cloudflare tunnel
• 88 tools organized across 12 capability groups
• OpenTelemetry instrumentation on every tool call, reporting to GitLab Observability
• OSSA-compliant: Follows Open Standard for Sustainable Agents specification
• Config resolution: Dynamic token substitution from workspace.json with template-based config generation

What It Connects

---

Architecture

Class Structure

The server is implemented as a single class AgentProtocolMCPServer in src/mcp/server.ts.

src/mcp/
  server.ts              # AgentProtocolMCPServer class (entry point)
  otel.ts                # OpenTelemetry instrumentation
  services/
    index.ts             # Service factory exports
    agent-registry.service.ts
    gitlab.service.ts
    compliance.service.ts
    vector-search.service.ts
    kubernetes.service.ts
    drupal-llm.service.ts
    workflow.service.ts
    ossa-agents.service.ts
    agent-sync.service.ts
    acquia-source.service.ts
    config.service.ts
  tools/
    knowledge-graph-tools.ts    # Tool definitions + handlers
    knowledge-graph-handlers.ts # Handler dispatch

SDK Usage

The server uses only official SDK types -- no custom HTTP layer:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
  Tool,
} from '@modelcontextprotocol/sdk/types.js';

Request Flow

MCP Client (Claude Desktop / Cursor / Custom)
   |
   | JSON-RPC (stdio or SSE)
   v
AgentProtocolMCPServer
   |
   |-- ListToolsRequestSchema --> getAllTools() --> returns 88 Tool definitions
   |
   |-- CallToolRequestSchema --> recordToolCall(name, args, fn)  [OTel traced]
   |       |
   |       v
   |   executeTool(name, args)
   |       |
   |       |-- group prefix routing (name.split('.')[0])
   |       |      agent.*    --> executeAgentTool()     --> AgentRegistryService
   |       |      platform.* --> executePlatformTool()   --> BlueFlyAgentPlatformClient
   |       |      gitlab.*   --> executeGitLabTool()     --> GitLabService
   |       |      compliance.* --> executeComplianceTool() --> ComplianceService
   |       |      vector.*   --> executeVectorTool()     --> VectorSearchService
   |       |      k8s.*      --> executeKuberneTool()    --> KubernetesService
   |       |      drupal.*   --> executeDrupalTool()     --> DrupalLLMService
   |       |      workflow.* --> executeWorkflowTool()   --> WorkflowService
   |       |      ossa.*     --> executeOSSATool()       --> OSSAAgentsService
   |       |      acquia.*   --> executeAcquiaSourceTool() --> AcquiaSourceService
   |       |      config.*   --> executeConfigTool()     --> ConfigService
   |       |      (underscore prefix) --> executeKnowledgeGraphTool()
   |       |
   |       v
   |   ToolExecutionResult { success, data, error?, metadata }
   |
   |-- ListResourcesRequestSchema --> getAllResources()
   |-- ReadResourceRequestSchema  --> readResource(uri)

Tool Dispatch

The executeTool() method routes by the prefix before the first dot:

const [group] = name.split('.');
switch (group) {
  case 'agent':      return this.executeAgentTool(name, args);
  case 'platform':   return this.executePlatformTool(name, args);
  case 'gitlab':     return this.executeGitLabTool(name, args);
  case 'compliance': return this.executeComplianceTool(name, args);
  case 'vector':     return this.executeVectorTool(name, args);
  case 'k8s':        return this.executeKuberneTool(name, args);
  case 'drupal':     return this.executeDrupalTool(name, args);
  case 'workflow':   return this.executeWorkflowTool(name, args);
  case 'ossa':       return this.executeOSSATool(name, args);
  case 'acquia':     return this.executeAcquiaSourceTool(name, args);
  case 'config':     return this.executeConfigTool(name, args);
  default:
    // Knowledge graph tools use underscores (query_knowledge_graph_*)
    if (name.startsWith('query_knowledge_graph_') || ...)
      return this.executeKnowledgeGraphTool(name, args);
    throw new Error(`Unknown tool: ${name}`);
}

Each group handler uses a dedicated service obtained via factory functions (getGitLabService(), getConfigService(), etc.) from src/mcp/services/index.ts.

---

Tool Reference (88 Tools)

Agent Registry (6 tools)

Platform Agents (6 tools)

These tools interact with the platform-agents service at mesh.bluefly.internal.

GitLab Ultimate (23 tools)

Core (7):

Observability (6):

Workspaces (3):

Security (2):

Model Registry (2):

KAS - Kubernetes Agent Server (2):

Protected Environments (1):

Compliance/OSSA (5 tools)

Vector Search / RAG (5 tools)

Kubernetes (6 tools)

Drupal LLM (5 tools)

Workflow (5 tools)

OSSA Agents (4 tools)

Knowledge Graph (6 tools)

These tools use underscore naming (not dot notation) and query the GitLab Knowledge Graph service.

Supported entity types: project, issue, merge_request, user, commit, milestone, label

Supported relationship types: HAS_ISSUE, HAS_MERGE_REQUEST, AUTHORED_BY, ASSIGNED_TO, CLOSES, REVIEWED_BY, TAGGED_WITH, HAS_COMMIT, HAS_MILESTONE, HAS_LABEL

Acquia Source (11 tools)

Integrates with Acquia Source (Drupal JSON:API) including Canvas page and component support.

Requires: ACQUIA_SOURCE_URL, ACQUIA_SOURCE_CLIENT_ID, ACQUIA_SOURCE_CLIENT_SECRET environment variables.

Config Resolution (6 tools)

---

SSE Transport

The SSE (Server-Sent Events) transport enables remote MCP connections, primarily for the Oracle Cloud deployment at mcp.blueflyagents.com.

HTTP Endpoints

Health Check Response

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

Connection Lifecycle

1. Client sends GET /sse to establish SSE stream
2. Server creates SSEServerTransport with /message as the post-back path
3. Server connects the MCP Server instance to the transport
4. Client sends JSON-RPC tool calls via POST /message
5. Server responds via the SSE stream

---

OpenTelemetry Integration

Module: src/mcp/otel.ts

Initialization

export async function initTracing(): Promise<void> {
  // Dynamically imports @opentelemetry/sdk-node and @opentelemetry/exporter-trace-otlp-http
  // If not installed, gracefully no-ops (api package provides no-op tracer)
  const sdk = new NodeSDK({
    serviceName: process.env.OTEL_SERVICE_NAME ?? 'agent-protocol',
    traceExporter: new OTLPTraceExporter({
      url: `${endpoint}/v1/traces`
    }),
  });
  sdk.start();
}

Tool Call Tracing

Every tool execution is wrapped via recordToolCall():

export async function recordToolCall<T>(
  toolName: string,
  args: Record<string, unknown>,
  result: () => Promise<T>
): Promise<T> {
  return withSpan(`mcp.tool.${toolName}`, async (span) => {
    span.setAttribute('mcp.tool.name', toolName);
    span.setAttribute('mcp.tool.group', toolName.split('.')[0]);
    const start = performance.now();
    try {
      const value = await result();
      span.setAttribute('mcp.tool.success', true);
      return value;
    } finally {
      span.setAttribute('mcp.tool.duration_ms', Math.round(performance.now() - start));
    }
  });
}

Span Attributes

Configuration

• Endpoint: http://87749026.otel.gitlab-o11y.com:4318/v1/traces (GitLab Observability)
• Required packages (optional -- gracefully no-ops if missing):
  • @opentelemetry/sdk-node
  • @opentelemetry/exporter-trace-otlp-http
• Always present: @opentelemetry/api (provides no-op tracer when SDK not installed)
• Shutdown: Hooks into SIGTERM for graceful SDK shutdown

---

Config Resolution System

The config resolution system provides template-based configuration with dynamic token substitution.

Token Resolver

The token resolver reads workspace.json from NAS (/Volumes/AgentPlatform/config/workspace.json) and substitutes $TOKEN placeholders in templates with actual values from the tokens section.

Config Templates

Located in src/config/templates/:

Merge Strategies

When syncing configs that may have local modifications, the system supports these merge strategies:

• preserve-secrets: Preserves locally-set secret values (tokens, keys)
• preserve-preferences: Preserves user-specific preferences
• preserve-hooks-plugins: Preserves custom hooks and plugin configurations

CLI Commands

# Sync all configs (resolve templates, write to output paths)
npx agent-protocol config sync
npx agent-protocol config sync --dry-run

# List available templates
npx agent-protocol config list

# Get a specific template resolved
npx agent-protocol config get settings
npx agent-protocol config get claude-desktop

# Check config service health
npx agent-protocol config health

# Get OTel configuration
npx agent-protocol config otel

---

Deployment

Docker Image

Dockerfile: infrastructure/Dockerfile.mcp-sse

Multi-stage build:

1. Build stage (node:20-alpine): Installs all dependencies, compiles TypeScript
2. Runtime stage (node:20-alpine): Production dependencies only, non-root user, tini as init, curl for healthcheck

FROM node:20-alpine AS builder
# ... npm ci, tsc ...

FROM node:20-alpine AS runtime
RUN apk add --no-cache curl tini
RUN addgroup -g 1001 -S appgroup && adduser -u 1001 -S appuser -G appgroup
# ... production npm ci, copy dist/ ...
USER appuser
HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
    CMD curl -f http://localhost:3100/health || exit 1
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/mcp/server.js"]

Docker Compose

File: infrastructure/docker-compose.mcp-sse.yml

Two services:

1. mcp-sse: The MCP SSE server on port 3100
2. cloudflared: Cloudflare tunnel sidecar that exposes mcp.blueflyagents.com

services:
  mcp-sse:
    build:
      context: ..
      dockerfile: infrastructure/Dockerfile.mcp-sse
    image: registry.gitlab.com/blueflyio/agent-platform/agent-protocol/mcp-sse:latest
    ports:
      - "3100:3100"
    environment:
      - MCP_TRANSPORT=sse
      - MCP_PORT=3100
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://87749026.otel.gitlab-o11y.com:4318
      - OTEL_SERVICE_NAME=agent-protocol
    volumes:
      - /Volumes/AgentPlatform/config/workspace.json:/app/config/workspace.json:ro
      - ~/.tokens/:/run/secrets/:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]

  cloudflared:
    image: cloudflare/cloudflared:latest
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
    depends_on:
      mcp-sse:
        condition: service_healthy

Public URL

mcp.blueflyagents.com via Cloudflare tunnel, pointing to the SSE server on port 3100.

CI/CD Pipeline

The .gitlab-ci.yml defines these stages:

Container Registry

registry.gitlab.com/blueflyio/agent-platform/agent-protocol/mcp-sse:latest

---

Running Locally

stdio Transport (Claude Desktop, CLI)

# Run directly with tsx (development)
npm run start:mcp-server

# Which executes:
tsx src/mcp/server.ts

This starts the MCP server on stdio transport, suitable for Claude Desktop's mcpServers configuration:

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

SSE Transport (Oracle mode testing)

# Run SSE server with verbose logging
npm run start:mcp-sse

# Which executes:
MCP_TRANSPORT=sse MCP_PORT=3100 MCP_VERBOSE=true tsx src/mcp/server.ts

Docker Build

# Build the SSE Docker image
npm run build:mcp-sse
# Which executes:
docker build -t agent-protocol-mcp-sse -f infrastructure/Dockerfile.mcp-sse .

Docker Compose (Full Stack)

# Start MCP SSE server + Cloudflare tunnel sidecar
docker compose -f infrastructure/docker-compose.mcp-sse.yml up -d

# View logs
docker compose -f infrastructure/docker-compose.mcp-sse.yml logs -f

# Stop
docker compose -f infrastructure/docker-compose.mcp-sse.yml down

Config Sync

# Sync all configs (resolve templates from workspace.json)
npx agent-protocol config sync

# Preview without writing
npx agent-protocol config sync --dry-run

# List available config templates
npx agent-protocol config list

# Resolve a single template
npx agent-protocol config get settings

# Check health
npx agent-protocol config health

# Get OpenTelemetry configuration
npx agent-protocol config otel

---

Environment Variables

---

MCP Resources

In addition to tools, the server exposes MCP resources that can be read by clients:

---

Related Documentation

• Architecture Overview -- System components, data flow, security model
• Agent Protocol npm guide -- npm package reference
• Separation of Duties -- Package ownership rules for @bluefly/agent-protocol
• MCP Registry API Reference -- MCP server discovery API
• Agent Protocol Audit -- Security audit report
• Oracle VM Disaster Recovery -- Oracle Cloud deployment recovery procedures
• MCP-First Architecture -- Platform-wide MCP architecture patterns
• GitLab Project: https://gitlab.com/blueflyio/agent-platform/agent-protocol
• MCP Specification: https://modelcontextprotocol.io/
• OSSA Standard: https://gitlab.com/blueflyio/openstandardagents