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.

• 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+)

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

• 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

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
}

Resource creation behavior based on quota usage:

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

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

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

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

{
  "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 → []

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

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

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)

{
  "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

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

npx @robinmordasiewicz/f5xc-api-mcp

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

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

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 mcp add f5xc-api -- npx @robinmordasiewicz/f5xc-api-mcp

Add to your MCP settings:

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

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".

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

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

# 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

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"
}

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.

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.

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.

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

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

• f5xc-api-virtual-http-loadbalancer-create
• f5xc-api-virtual-origin-pool-list
• f5xc-api-cemanagement-network-interface-get
• f5xc-api-server-info

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

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

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)

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

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

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

The server automatically normalizes various URL formats:

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

If your organization uses a custom CA:

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

WARNING: Never use in production!

export F5XC_TLS_INSECURE=true

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.

• Node.js 24+
• npm 9+

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

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

npm run lint          # Check linting
npm run lint:fix