IO River MCP Server — Usage Guide
The IO River MCP server exposes your IO River account as a set of AI-callable tools via the Model Context Protocol. It allows AI assistants (such as Claude) to manage CDN services, traffic policies, certificates, monitors, analytics, and more — all through natural language.
Authentication
Every request to the MCP endpoint must include a Bearer token in the Authorization header:
Authorization: Bearer <your-ioriver-api-token>
You can generate an API token from your IO River dashboard. The token is passed through transparently to the IO River API and is never stored server-side.
Connecting an AI Client
Claude Desktop (via mcp-remote)
Add the following to your Claude Desktop configuration file (claude_desktop_config.json):
{
"mcpServers": {
"ioriver": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.ioriver.io/mcp", "--header", "Authorization: Bearer ${IORIVER_API_TOKEN}"]
}
}
}
Set the IORIVER_API_TOKEN environment variable to your API token, or replace ${IORIVER_API_TOKEN} with the token value directly.
Direct HTTP (Streamable HTTP transport)
The server speaks the MCP Streamable HTTP transport. Send requests to:
POST https://mcp.ioriver.io/mcp
Authorization: Bearer <your-ioriver-api-token>
Content-Type: application/json
Account Providers
Manage CDN providers connected to your IO River account (e.g. Cloudflare, Akamai, Fastly).
| Tool | Description |
|---|
list_account_providers | List all CDN providers connected to your account |
get_account_provider | Get details of a specific provider by ID |
create_account_provider | Connect a new CDN provider to your account |
update_account_provider | Update credentials or display name of a provider |
delete_account_provider | Remove a CDN provider from the account permanently |
Services
A service is the top-level resource representing a CDN-accelerated application.
| Tool | Description |
|---|
list_services | List all services in your account |
get_service | Get details of a specific service |
create_service | Create a new service |
update_service | Update a service's name or description |
delete_service | Delete a service permanently |
Domains
| Tool | Description |
|---|
list_domains | List all domains for a service |
create_domain | Add a domain to a service |
update_domain | Update an existing domain |
delete_domain | Delete a domain from a service |
Origins
| Tool | Description |
|---|
list_origins | List all origin (backend) servers for a service |
create_origin | Add an origin server (required: host) |
update_origin | Update an existing origin |
delete_origin | Remove an origin from a service |
Service Providers
| Tool | Description |
|---|
list_service_providers | List CDN providers attached to a service |
add_service_provider | Attach a CDN provider to a service |
remove_service_provider | Detach a CDN provider from a service |
Traffic Policies
Traffic policies control how requests are routed across CDN providers.
| Tool | Description |
|---|
list_traffic_policies | List all traffic policies for a service |
get_traffic_policy | Get details of a specific policy |
create_traffic_policy | Create a new traffic policy |
update_traffic_policy | Update an existing traffic policy |
delete_traffic_policy | Delete a traffic policy |
Behaviors
Behaviors define cache rules, routing logic, and request/response transformations.
| Tool | Description |
|---|
list_behaviors | List all behaviors for a service |
get_behavior | Get details of a specific behavior |
create_behavior | Create a new behavior |
update_behavior | Update an existing behavior |
delete_behavior | Delete a behavior from a service |
Certificates
| Tool | Description |
|---|
list_certificates | List all SSL/TLS certificates in your account |
get_certificate | Get details of a specific certificate |
create_certificate | Add a new certificate |
update_certificate | Update an existing certificate |
delete_certificate | Delete a certificate |
Monitors
Health Checks
| Tool | Description |
|---|
list_health_checks | List all health checks for a service |
get_health_check | Get a specific health check by ID |
create_health_check | Create a new health check |
update_health_check | Update an existing health check |
delete_health_check | Delete a health check |
| Tool | Description |
|---|
list_performance_checks | List all performance checks for a service |
get_performance_check | Get a specific performance check by ID |
create_performance_check | Create a new performance check |
update_performance_check | Update an existing performance check |
delete_performance_check | Delete a performance check |
Alerts
| Tool | Description |
|---|
list_alerts | List all alerts configured in your account |
list_alert_channels | List notification channels (Slack, email, etc.) |
test_alert | Trigger a test notification for an alert |
Cache Purge
| Tool | Description |
|---|
get_purge_history | Get purge history for a service within a time range |
purge_cache | Purge specific URLs or URL patterns from CDN cache |
purge_cache_tags | Purge cached content by cache tags |
purge_all | Purge the entire CDN cache for a service (use with caution) |
Analytics
Traffic Analytics
| Tool | Description |
|---|
get_traffic_analytics_overtime | Get traffic metrics over time |
get_traffic_analytics_top_stats | Get top-N traffic statistics (e.g. top URLs, ASNs) |
get_traffic_analytics_sampled_logs | Get sampled request logs |
Traffic Stats
| Tool | Description |
|---|
get_traffic_stats | Get traffic statistics over time per CDN provider, useful for cost and performance analysis |
Security Analytics
| Tool | Description |
|---|
get_security_requests_overtime | Get security event counts over time |
get_security_top_stats | Get top security statistics (e.g. top blocked IPs) |
get_security_sampled_logs | Get sampled security event logs |
Events
| Tool | Description |
|---|
get_traffic_events_for_service | Get traffic events for a specific service |
get_traffic_events_for_account | Get traffic events across the entire account |
Example Prompts
Below are example prompts you can use with an AI assistant connected to this MCP server:
- "List all my IO River services"
- "Show traffic policies for service abc123"
- "Purge the cache for /images/* on service abc123"
- "Show traffic stats for the last 24 hours on service abc123"
- "Which countries had the most traffic in the last day?"
- "What traffic was blocked by security in the last 24 hours?"
- "Show me the top security threats on service abc123 today"
- "Create a behavior to cache /static/* for 5 minutes"
- "Add a Fastly provider to my service abc123 and route 50% of the traffic to it"
- "Are there any active alerts?"
Self-Hosting
You can run your own instance of the IO River MCP server. The source code is available on GitHub:
github.com/ioriver/mcp
Running with Docker
docker build -t ioriver-mcp .
docker run -p 8000:80 ioriver-mcp
Running locally
# Install dependencies
pip install pipenv
pipenv install
# Start the server
pipenv run python src/main.py
The server will be available at http://localhost:8000/mcp.