gatekeeper-mcp-server 3.0.0b6

FastMCP-based server exposing CAST Dashboard REST API via Model Context Protocol

Gatekeeper MCP Server

A FastMCP-based server that exposes CAST Imaging REST API functionality through the Model Context Protocol (MCP), enabling AI agents like Claude, GitHub Copilot, and Cursor to interact with application quality, compliance, and security data via natural language.

Requirements

• Python 3.12 or higher
• CAST Imaging 3.6.2-funcrel or higher (with imaging-services component)
• Valid CAST Imaging API key
• TCP port 8283 (default, configurable)
• 2 GB minimum free disk space
• MCP-aware client: GitHub Copilot, Claude Desktop, or Cursor

Installation

Option 1: PyPI (Recommended)

pip install gatekeeper-mcp-server

Option 2: Docker

cd deploy/server
./run.sh

Configuration

Step 1 — Verify CAST Imaging connectivity

curl -H "x-api-key: <api-key>" http://<imaging-host>:8090/dashboards/rest/

Step 2 — Create app.config

# Required
HOST_CONTROL_PANEL=<imaging-services-host>
PORT_CONTROL_PANEL=8098

# Authentication
DASHBOARD_API_KEY=your-api-key

# MCP Server
MCP_SERVER_PORT=8283
SERVICE_HOST=<mcp-server-ip-or-hostname>

# SSL (set true if imaging-services uses HTTPS)
CONTROL_PANEL_SSL_ENABLED=false

Configuration Priority

1. Command-line --config argument
2. Environment variables (UPPER_CASE)
3. Config file values
4. Default values

Authentication Methods

The server resolves credentials in this order (highest priority first):

Method	Format
Request header	x-api-key: your-api-key
Request header	Authorization: Bearer your-token
Config file	DASHBOARD_API_KEY=your-api-key
Environment variable	DASHBOARD_API_KEY=your-api-key

Running the Server

With config file:

gatekeeper-mcp-server --config /path/to/app.config

With environment variables:

HOST_CONTROL_PANEL=your-host PORT_CONTROL_PANEL=8098 gatekeeper-mcp-server

PowerShell:

$env:HOST_CONTROL_PANEL = "your-host"
$env:PORT_CONTROL_PANEL = "8098"
$env:DASHBOARD_API_KEY  = "your-api-key"
gatekeeper-mcp-server

Verify the Server is Running

curl http://localhost:8090/mcp/gatekeeper/healthcheck

Expected response:

{"status": "healthy", "service": "GatekeeperMCPServer"}

Client Integration

The MCP server URL for direct (non-proxied) installation is http://<host>:8283/mcp.

VS Code with GitHub Copilot

Create .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "dashboard-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    }
  ],
  "servers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "${input:dashboard-key}"
      }
    }
  }
}

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

The MCP server must be running before connecting clients.

URL Formats

Deployment	URL
Direct (PyPI / source)	http://localhost:8283/mcp
Behind nginx proxy (HTTP)	http://<host>:8090/mcp/gatekeeper
Behind nginx proxy (HTTPS)	https://<host>/mcp/gatekeeper
Custom HTTPS port	https://<host>:8443/mcp/gatekeeper

Available Tools

get_compliance_status

Get compliance status for an application with quality indicators, violations, and technical debt.

Parameters:

• application_name (required): Application name
• quality_indicators (optional): Comma-separated quality-indicator IDs (e.g., "60017,4672")
• snapshot (optional): Snapshot number, "first_last", or "all"
• standard (optional): Filter by standard — "ISO-5055", "CISQ", "OWASP"
• technologies (optional): Technology filter (comma-separated or "$all")
• modules (optional): Module filter (comma-separated or "$all")

get_technical_debt

Get technical debt metrics including remediation effort in minutes and days.

get_violations

Get detailed violations with code-level diagnosis including file paths, line numbers, and execution paths. Supports filtering by rule pattern, criticality, status, technologies, and business criteria.

Example natural language queries:

Get compliance status for MyApp with ISO-5055 standard
Show security violations for MyApp
What is the technical debt for MyApp?

Architecture

MCP Client (Claude / Copilot / Cursor)
    │ Streamable HTTP — port 8283/mcp
    ▼
Tool Layer          (quality_tools.py)
    ▼
Business Logic      (dashboard_service.py)   validation, caching, normalization
    ▼
Data Access         (dashboard_server.py)    HTTP client, connection pooling, auth
    ▼
CAST Imaging REST API

Key Files

File	Role
server/run_server.py	Entry point, health check routes
server/config.py	Multi-source configuration
server/services/dashboard_api/tools/quality_tools.py	MCP tool definitions
server/services/dashboard_api/utils/dashboard_service.py	Business logic
server/services/dashboard_api/dashboard_server.py	HTTP client
server/shared/	Validators, exceptions, logging, middleware

Security

• Input validation: path traversal, SQL injection, length overflow, header injection prevention
• SSL/TLS: terminated externally (nginx) or via SSL_CERT_FILE env var for corporate CAs
• Credentials: never logged; resolved from headers → config → environment
• Rate limiting: configured in nginx (limit_req_zone / limit_req)

Corporate / Self-Signed CA Certificates

# Windows
$Env:SSL_CERT_FILE = "C:\path\to\ca-chain.pem"
gatekeeper-mcp-server --config app.config

# Linux
SSL_CERT_FILE=/path/to/ca-chain.pem gatekeeper-mcp-server --config app.config

Monitoring & Logging

Health check:

curl http://localhost:8090/mcp/gatekeeper/healthcheck

Log location (PyPI install):

logs/mcp_gatekeeper.log   (rotating: 30 files × 10MB, gzipped)

Enable debug logging:

DEBUG_MODE=true

Troubleshooting

"Dashboard API is not available"

• Check HOST_CONTROL_PANEL and PORT_CONTROL_PANEL in config
• Test connectivity: curl -H "x-api-key: <key>" http://<imaging-host>:8090/dashboards/rest/

"No applications will be authorized"

• Verify API key is valid and has application permissions in CAST Imaging

Port already in use

• Change MCP_SERVER_PORT in config or stop the existing process

SSL/TLS errors

• Set SSL_CERT_FILE to your PEM chain file before starting

Rate limit exceeded (HTTP 429)

• Adjust limit_req_zone rate or limit_req burst in deploy/server/nginx/nginx.conf

Docker Deployment

cd deploy/server
./run.sh

Or with Docker Compose:

services:
  mcp-server:
    image: gatekeeper-mcp-server
    ports:
      - "8283:8283"
    environment:
      - HOST_CONTROL_PANEL=your-imaging-host
      - PORT_CONTROL_PANEL=8098
      - DASHBOARD_API_KEY=your-api-key
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

Development

See CLAUDE.md for developer documentation on extending the server.

# Run tests
pytest

# Health check
curl http://localhost:8283/mcp/healthcheck