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:

Zone	Usage	Behavior
🟢 Green	0-79%	Creation allowed, no warnings
🟡 Yellow	80-99%	Creation allowed, warning logged
🔴 Red	100%+	Creation blocked with error

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

Field	Default Value
spec.jitter_percent	0
spec.http_health_check.use_http2	false
spec.http_health_check.headers	{}
spec.http_health_check.expected_status_codes	[] (accepts 200-299)
spec.http_health_check.request_headers_to_remove	[]

Recommended Values (Web UI Defaults)

Field	Recommended
spec.timeout	3 seconds
spec.interval	15 seconds
spec.unhealthy_threshold	1 failure
spec.healthy_threshold	3 successes
spec.jitter_percent	30% (production)

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

Field	Server Default	UI Default	Note
spec.loadbalancer_algorithm	ROUND_ROBIN	LB_OVERRIDE	⚠️ Discrepancy!
spec.endpoint_selection	DISTRIBUTED	-	Distributed selection
TLS to origin (spec.no_tls)	Disabled	-	No TLS by default
Connection timeout	2000 ms	-	2 second timeout
HTTP idle timeout	300000 ms	-	5 minute timeout
Circuit breaker	Default enabled	-	Auto-enabled
Outlier detection	Disabled	-	Must enable explicitly
HTTP protocol	Auto-negotiation	-	auto_http_config
Proxy protocol	Disabled	-	Must enable explicitly

⚠️ 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:

Field Group	Options	Purpose
Port	port | automatic_port | lb_port	Origin server port selection
TLS	no_tls | use_tls	TLS configuration to origin
Circuit Breaker	default_circuit_breaker | disable_circuit_breaker | circuit_breaker	Circuit breaker behavior
HTTP Protocol	auto_http_config | http1_config | http2_options	HTTP protocol negotiation
Health Check Port	same_as_endpoint_port | health_check_port	Health check port selection

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

Variable	Required	Description
F5XC_API_URL	For execution	Tenant URL (auto-normalized)
F5XC_API_TOKEN	For token auth	API token from XC Console
F5XC_P12_BUNDLE	For cert auth	Path to P12 certificate bundle
F5XC_P12_PASSWORD	For cert auth	Password for P12 certificate
F5XC_PROFILE	No	Profile name to use (default: active profile from config)
F5XC_TLS_INSECURE	No	Disable SSL verification (staging only, set to true)
F5XC_CA_BUNDLE	No	Path to custom CA certificate bundle
F5XC_QUOTA_CHECK_ENABLED	No	Enable quota validation (default: true)
F5XC_QUOTA_CACHE_TTL	No	Quota cache TTL in seconds (default: 300)
F5XC_QUOTA_GREEN_THRESHOLD	No	Green zone percentage (default: 79)
F5XC_QUOTA_YELLOW_THRESHOLD	No	Yellow zone percentage (default: 99)
F5XC_QUOTA_RED_THRESHOLD	No	Red zone percentage (default: 100)
LOG_LEVEL	No	Logging verbosity (debug, info, warn, error)

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:

Action	Description
status	Check current authentication state and active profile
configure	Save new credentials to a named profile
list-profiles	List all available profiles
set-active	Switch the active profile

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)

Domain	Path Count	Structure	Description
AI Intelligence	11	2-level	AI assistant, BFDP
API Security	45	2-level	API discovery, protection, definitions
BIG-IP Integration	28	2-level	BIG-IP virtual servers, iRules, APM
Billing	19	2-level	Invoices, payment methods, subscriptions
CDN	31	2-level	CDN load balancers, cache rules
DNS	42	2-level	DNS zones, DNS load balancers, DNS pools
Infrastructure	134	3-level	AWS/Azure/GCP VPC sites, customer edge sites
Infrastructure Protection	72	2-level	DDoS protection, firewall rules
Integrations	26	2-level	Third-party apps, ticket systems
Identity	137	3-level	Authentication, users, roles, RBAC
Load Balancing	89	2-level	HTTP/TCP/UDP load balancers, origin pools, forward proxy
Monitoring & Observability	235	3-level	Alerts, logs, synthetic monitors, metrics
NGINX Integration	34	2-level	NGINX One instances, servers, service discovery
Networking	220	3-level	Network connectors, firewalls, interfaces, policies
Operations	22	2-level	Debug, DHCP, ping, traceroute
Regional Edge Configuration	18	2-level	Regional edge settings, policies
Security	210	3-level	Service policies, WAF, malicious user mitigation
Service Mesh	31	2-level	Virtual K8s, workloads, K8s clusters
Shape Security (Bot Defense)	124	3-level	Bot defense, client-side defense
System Configuration	23	2-level	Namespaces, certificates, credentials
Tenant Management	28	2-level	Multi-tenant management, profiles
VPN	20	2-level	VPN tunnels, IKE profiles
Workflows & Automation	15	2-level	Workflow templates, automations

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:

User Input	Normalized
tenant.volterra.us	tenant.console.ves.volterra.io/api
tenant.console.ves.volterra.io	tenant.console.ves.volterra.io/api
https://tenant.volterra.us/	https://tenant.console.ves.volterra.io/api

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

Error	Cause	Solution
Hostname/IP does not match certificate's altnames	Staging URL mismatch	Use F5XC_TLS_INSECURE=true or custom CA
self signed certificate	Custom CA not trusted	Set F5XC_CA_BUNDLE
certificate has expired	Expired certificate	Contact F5 XC admin
unable to verify the first certificate	Missing intermediate CA	Add intermediates to CA bundle

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