F5 Distributed Cloud API MCP Server

An MCP (Model Context Protocol) server that exposes F5 Distributed Cloud APIs to AI assistants. Enables natural language interaction with F5XC infrastructure through Claude, VS Code, and other MCP-compatible tools.

Features

• 1500+ API Tools - Complete coverage of F5XC API operations across 23 enriched domains

• Domain-Based Documentation - Tools organized by domains with intelligent 2-level and 3-level hierarchical navigation

• Dual-Mode Operation - Works without authentication (documentation mode) AND with authentication (execution mode)

• CURL Examples - API documentation with curl commands for authenticated and unauthenticated modes

• Multiple Auth Methods - API token and P12 certificate (mTLS) support

• URL Normalization - Automatically handles various F5XC URL formats

• Pre-enriched Specs - Uses optimized OpenAPI 3.0.3 specifications with domain metadata

• Server-Applied Defaults - Distinguishes user-required fields from server-defaulted fields (v2.0.28+)

• Quota Awareness - Pre-flight quota validation prevents resource creation failures (v2.1.0+)

Quota Awareness

The MCP server automatically checks resource quota availability before executing create operations, preventing failures due to quota limits.

Features

• Pre-Flight Validation - Checks quota before API calls

• Automatic Blocking - Prevents creation when quota is at 100%

• Warning System - Warns when quota usage is 80-99%

• Caching - 5-minute cache reduces API calls

• Per-Namespace Tracking - Quota limits checked per namespace

• Configurable Thresholds - Customize warning and blocking levels

Quota MCP Tools

Three MCP tools provide visibility into quota usage:

f5xc-api-get-quota-status

// Get quota status for a specific resource type
{
  "namespace": "production",
  "resourceType": "healthcheck"
}

// Output:
// Quota Status for healthcheck
// Namespace: production
// Current Usage: 95/100 (95%)
// Remaining: 5
// Status: ⚠️ Approaching limit

f5xc-api-list-namespace-quotas

// List all quota limits for a namespace
{
  "namespace": "production",
  "showOnlyLimited": false
}

// Output: Table of all resource quotas with usage

f5xc-api-clear-quota-cache

// Clear quota cache to force fresh API queries
{
  "namespace": "production"  // optional
}

Quota Thresholds

Resource creation behavior based on quota usage:

Example Error Message

When quota limit is reached:

ERROR: Resource quota limit reached

Resource Type: healthcheck
Namespace: production
Current Usage: 100/100 (100%)
Status: ❌ At limit - cannot create additional resources

Action Required:
1. Delete unused healthcheck resources in the 'production' namespace
2. Request quota increase from F5 XC support
3. Use a different namespace with available quota

Configuration

Control quota checking behavior via environment variables:

# Enable/disable quota checking (default: true)
export F5XC_QUOTA_CHECK_ENABLED=true

# Cache TTL in seconds (default: 300 = 5 minutes)
export F5XC_QUOTA_CACHE_TTL=300

# Threshold percentages (defaults: 79, 99, 100)
export F5XC_QUOTA_GREEN_THRESHOLD=79
export F5XC_QUOTA_YELLOW_THRESHOLD=99
export F5XC_QUOTA_RED_THRESHOLD=100

Server-Applied Default Values

F5 XC API specifications (v2.0.28+) distinguish between field requirements with enhanced metadata:

Field Requirement Types

1. User-Required Fields (x-f5xc-required-for.create: true)

   • Must be provided by user at creation time

   • Validation returns error if missing

   • Example: metadata.name, http_health_check.path

2. Server-Defaulted Fields (x-f5xc-server-default: true)

   • Optional at creation time

   • Server applies default value if omitted

   • Validation returns warning with default value info

   • Example: healthcheck.jitter_percent defaults to 0

3. Recommended Values (x-f5xc-recommended-value) - v2.0.32+

   • Suggested values matching F5 XC web UI defaults

   • Provides guidance without enforcing specific values

   • Example: spec.timeout recommended value is 3

4. Schema-Required Fields (x-ves-required: true)

   • Must have non-zero value when API processes the request

   • Can be user-provided OR server-defaulted

Healthcheck Configuration (v2.0.32+)

Server-Applied Defaults

Recommended Values (Web UI Defaults)

Example: Minimal Healthcheck Configuration

{
  "metadata": {
    "name": "example-hc",
    "namespace": "default"
  },
  "spec": {
    "timeout": 3,
    "interval": 15,
    "unhealthy_threshold": 1,
    "healthy_threshold": 3,
    "http_health_check": {
      "use_origin_server_name": {},
      "path": "/health"
    }
  }
}

Server automatically applies:

• spec.jitter_percent → 0

• spec.http_health_check.use_http2 → false

• spec.http_health_check.headers → {}

• spec.http_health_check.expected_status_codes → []

Origin Pool Configuration (v2.0.33+)

Server-Applied Defaults

⚠️ Critical UI vs Server Discrepancy: The web console pre-selects LB_OVERRIDE for the load balancer algorithm, but the server applies ROUND_ROBIN when the field is omitted. This creates behavior mismatches between UI-created and API-created configurations.

OneOf Field Patterns (Mutually Exclusive)

Origin pools use mutually exclusive field groups where only one option should be specified:

Required Fields

Origin pool configurations must include:

• metadata.name - Unique identifier

• metadata.namespace - Target namespace

• At least one spec.origin_servers entry

• Explicit port (1-65535 range via port, automatic_port, or lb_port)

Example: Minimal Origin Pool Configuration

{
  "metadata": {
    "name": "example-origin-pool",
    "namespace": "default"
  },
  "spec": {
    "origin_servers": [
      {
        "public_ip": {
          "ip": "192.0.2.1"
        }
      }
    ],
    "port": 443,
    "use_tls": {
      "use_host_header_as_sni": {}
    }
  }
}

Server automatically applies:

• spec.loadbalancer_algorithm → ROUND_ROBIN

• spec.endpoint_selection → DISTRIBUTED

• Connection timeout → 2000 ms

• HTTP idle timeout → 300000 ms

• Circuit breaker → Default enabled

• HTTP protocol → Auto-negotiation

Validation Behavior

When validating parameters:

• Missing user-required field → ❌ Error: "Missing required field: metadata.name"

• Missing server-default field → ⚠️ Warning: "Field 'jitter_percent' will default to 0"

• Recommended values → 📋 Info: Returned in recommendedValues for guidance

Quick Start

Using npx (Recommended)

npx @robinmordasiewicz/f5xc-api-mcp

Using npm

npm install -g @robinmordasiewicz/f5xc-api-mcp
f5xc-api-mcp

Using Docker

docker run -i --rm ghcr.io/robinmordasiewicz/f5xc-api-mcp

Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "f5xc-api": {
      "command": "npx",
      "args": ["@robinmordasiewicz/f5xc-api-mcp"],
      "env": {
        "F5XC_API_URL": "https://your-tenant.console.ves.volterra.io",
        "F5XC_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code CLI

claude mcp add f5xc-api -- npx @robinmordasiewicz/f5xc-api-mcp

VS Code (with Cline/Continue)

Add to your MCP settings:

{
  "mcpServers": {
    "f5xc-api": {
      "command": "npx",
      "args": ["@robinmordasiewicz/f5xc-api-mcp"]
    }
  }
}

OpenCode

Add to opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "f5xc-api": {
      "type": "local",
      "command": ["npx", "@robinmordasiewicz/f5xc-api-mcp"],
      "environment": {
        "F5XC_API_URL": "https://your-tenant.console.ves.volterra.io",
        "F5XC_API_TOKEN": "your-api-token"
      }
    }
  }
}

Note: OpenCode uses different schema: "mcp" key (not "mcpServers"), array-based "command", "environment" (not "env"), and requires "type": "local".

Environment Variables

Profile-Based Configuration

Manage multiple F5XC tenant credentials with named profiles stored in ~/.config/f5xc/profiles/.

Profile Management via MCP Tool

Use the f5xc-api-configure-auth MCP tool through your AI assistant:

Example interactions:

"Check my F5XC authentication status"
→ Uses f5xc-api-configure-auth with action: status

"Configure a new F5XC profile called production"
→ Uses f5xc-api-configure-auth with action: configure

"Switch to the staging profile"
→ Uses f5xc-api-configure-auth with action: set-active

Using Profiles

# Use active profile (from ~/.config/f5xc/active_profile)
f5xc-api-mcp

# Use specific profile via environment variable
F5XC_PROFILE=staging f5xc-api-mcp

# Override profile credentials with environment variables
F5XC_PROFILE=production F5XC_API_TOKEN=temporary-token f5xc-api-mcp

Configuration Directory Structure

Profiles are stored in ~/.config/f5xc/ (XDG Base Directory compliant):

~/.config/f5xc/
├── active_profile       # Contains the name of the active profile
└── profiles/
    ├── production.json  # Individual profile files
    └── staging.json

Profile file format (~/.config/f5xc/profiles/production.json):

{
  "name": "production",
  "tenant_url": "https://mytenant.console.ves.volterra.io",
  "api_token": "your-api-token",
  "created_at": "2025-12-21T10:00:00Z",
  "last_used_at": "2025-12-21T15:30:00Z"
}

Credential Priority

Credentials are loaded in this order (highest to lowest priority):

1. Environment Variables - F5XC_API_URL, F5XC_API_TOKEN, etc.

2. Active Profile - Selected by F5XC_PROFILE or from ~/.config/f5xc/active_profile

3. Documentation Mode - No credentials (read-only API documentation)

Environment variables always override profile settings, enabling temporary overrides.

Backward Compatibility

Existing setups using environment variables continue to work unchanged:

export F5XC_API_URL=https://mytenant.console.ves.volterra.io
export F5XC_API_TOKEN=your-api-token
f5xc-api-mcp

No changes needed - profiles are optional.

Dual-Mode Operation

Documentation Mode (No Authentication)

When no credentials are provided, the server provides:

• OpenAPI specification documentation

• API operation explanations

• Parameter descriptions and validation

• CURL command examples

• JSON request templates

This mode is ideal for exploring the API and understanding available operations.

Execution Mode (With Authentication)

When credentials are provided, the server additionally:

• Executes actual API calls against your tenant

• Lists and retrieves resources

• Creates, updates, and deletes configurations

• Returns real-time resource status

Available Tools

Tools follow the naming pattern: f5xc-api-{domain}-{resource}-{operation}

Domains (23 Total)

Example Tools

• f5xc-api-virtual-http-loadbalancer-create

• f5xc-api-virtual-origin-pool-list

• f5xc-api-cemanagement-network-interface-get

• f5xc-api-server-info

Documentation Structure

The documentation site is automatically generated from enriched OpenAPI specifications and organized by domain with intelligent hierarchical navigation:

Two-Level Navigation (Small Domains < 50 paths)

Small domains use a simple 2-level structure: Domain → Resource

docs/tools/
├── vpn/
│   ├── ipsec-gateway.md
│   └── vpn-connection.md
├── cdn/
│   ├── cdn-loadbalancer.md
│   └── cdn-pool.md

Example: VPN Tools

Three-Level Navigation (Large Domains ≥ 50 paths)

Large domains use a 3-level structure: Domain → Category (by OpenAPI tag) → Resource

docs/tools/
├── observability/
│   ├── alerts-events/
│   │   ├── alert-policy.md
│   │   └── event-manager.md
│   ├── logging/
│   │   ├── access-log.md
│   │   └── audit-log.md
│   └── metrics-statistics/
│       └── metric-collector.md

Large domains (>50 paths) using 3-level navigation:

• Monitoring & Observability (235 paths)

• Networking (220 paths)

• Security (210 paths)

• Infrastructure (134 paths)

• Identity (137 paths)

• Shape Security (124 paths)

Automatic Generation

Documentation is automatically generated by the build system:

# Generate/regenerate documentation
npm run generate-docs

# Build documentation site
mkdocs build

# Preview site locally
mkdocs serve

The generator automatically:

• Converts domain titles from snake_case to display format (e.g., load_balancer → "Load Balancing")

• Updates mkdocs.yml navigation without manual changes

• Creates markdown files with API operation details and examples

• Subdivides large domains based on OpenAPI operation tags

• Maintains consistent directory structure and naming conventions

Workflow Prompts

The server includes guided workflow prompts sourced from upstream enriched specs:

• deploy_http_loadbalancer - Create a fully configured HTTP load balancer with backend origin pool

• deploy_https_loadbalancer - Create HTTPS load balancer with SSL/TLS termination

• enable_waf_protection - Add web application firewall to existing load balancer

• configure_origin_pool - Set up backend server pool with health checks

• configure_dns_zone - Set up authoritative DNS zone with records

• enable_cdn_distribution - Configure CDN for content delivery

• register_site - Register and configure a CE site

Resource URIs

Access F5XC resources via URI scheme:

f5xc://{tenant}/{namespace}/{resource-type}/{name}

Examples:

• f5xc://mytenant/production/http_loadbalancer/my-app

• f5xc://mytenant/system/namespace/default

URL Normalization

The server automatically normalizes various URL formats:

SSL/TLS Configuration

Staging Environment Certificate Issue

F5 XC staging environments use URLs like tenant.staging.console.ves.volterra.io, but the SSL certificate only covers *.console.ves.volterra.io. This causes SSL validation failures because wildcards only match a single subdomain level, not two levels (tenant.staging).

Error Example:

Hostname/IP does not match certificate's altnames:
Host: tenant.staging.console.ves.volterra.io
Cert covers: DNS:*.console.ves.volterra.io, DNS:console.ves.volterra.io

Solutions

Option 1: Custom CA Bundle (Recommended)

If your organization uses a custom CA:

export F5XC_CA_BUNDLE=/path/to/your/ca-bundle.crt

Option 2: Disable Verification (Development Only)

WARNING: Never use in production!

export F5XC_TLS_INSECURE=true

Troubleshooting SSL Errors

Security Best Practices

1. Prefer F5XC_CA_BUNDLE over F5XC_TLS_INSECURE: Using a custom CA bundle maintains certificate validation while trusting your organization's certificates.

2. Contact F5 Support: For staging environments, contact F5 Support to request the official staging environment CA certificate. This is the most secure long-term solution.

3. Never use F5XC_TLS_INSECURE=true in production: This setting disables all certificate validation and should only be used for development and testing.

4. Rotate credentials regularly: API tokens and certificates should be rotated according to your organization's security policies.

Development

Prerequisites

• Node.js 24+

• npm 9+

Setup

git clone https://github.com/robinmordasiewicz/f5xc-api-mcp.git
cd f5xc-api-mcp
npm install
npm run build

Testing

npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Linting

npm run lint          # Check linting
npm run lint:fix      # Fix linting issues
npm run format        # Format code

Documentation

Full documentation is available at: https://robinmordasiewicz.github.io/f5xc-api-mcp

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE for details.

Support

• GitHub Issues

• GitHub Discussions