MCP Server¶
ByteFreezer provides an MCP (Model Context Protocol) server that exposes the full Control API as tools for AI coding assistants. Connect Claude Code, Cursor, or any MCP-compatible client and manage your entire ByteFreezer deployment through natural language.
How It Works¶
The MCP server is a stateless HTTP proxy between your AI assistant and the Control API. It translates MCP tool calls into authenticated REST requests:
AI Assistant ──MCP──▶ ByteFreezer MCP Server ──REST──▶ Control API
(mcp.bytefreezer.com) (api.bytefreezer.com)
All access control is enforced by the Control API. The MCP server passes your API key through and adds no state of its own.
Integration¶
Claude Code¶
claude mcp add --transport http bytefreezer --scope user \
https://mcp.bytefreezer.com/mcp \
--header "Authorization: Bearer <your-api-key>"
Replace <your-api-key> with your ByteFreezer API key. Generate one in the UI under Account Settings, or use the bf_generate_api_key tool after initial setup.
Restart Claude Code after adding. Verify with:
To remove:
Self-Hosted MCP Server¶
If you run your own Control API, point the MCP server at it instead of mcp.bytefreezer.com.
Then add your local instance to Claude Code:
claude mcp add --transport http bytefreezer --scope user \
http://localhost:8080/mcp \
--header "Authorization: Bearer <your-api-key>"
Other MCP Clients¶
Any client that supports MCP Streamable HTTP transport can connect. The server exposes two endpoints:
| Path | Description |
|---|---|
/mcp | MCP Streamable HTTP endpoint |
/health | Health check ({"status":"ok"}) |
Authentication¶
The MCP server passes the Authorization header from each request through to the Control API. Your API key determines what you can see and do:
- System admin keys can access all accounts, tenants, and datasets
- Account keys can only access their own account data
Generate API keys via the UI or the bf_generate_api_key tool.
Tools¶
78 tools organized into 12 categories.
Health (7)¶
Monitor service health across your deployment.
| Tool | Description |
|---|---|
bf_health_check | Check if Control API is reachable |
bf_health_status | Detailed health of all registered services |
bf_health_summary | Count of healthy/unhealthy/degraded services |
bf_health_service | Health for a specific service type (proxy, receiver, piper, packer) |
bf_ecosystem_health | Ecosystem-wide health snapshot |
bf_proxies_health | All proxy health status (system admin) |
bf_system_stats | DB pool health, connections, uptime |
Accounts (10)¶
Manage accounts, API keys, and service keys.
| Tool | Description |
|---|---|
bf_list_accounts | List all accounts (system admin) |
bf_get_account | Get account details |
bf_create_account | Create account (on_prem or enterprise) |
bf_update_account | Update account |
bf_delete_account | Delete account |
bf_list_api_keys | List API keys for account |
bf_generate_api_key | Generate new API key |
bf_revoke_api_key | Revoke an API key |
bf_list_service_keys | List service keys (used by on-prem services) |
bf_generate_service_key | Generate service key |
Tenants (6)¶
Manage tenants within accounts.
| Tool | Description |
|---|---|
bf_list_all_tenants | List all tenants across accounts (system admin) |
bf_list_tenants | List tenants for an account |
bf_get_tenant | Get tenant details |
bf_create_tenant | Create tenant |
bf_update_tenant | Update tenant |
bf_delete_tenant | Delete tenant |
Datasets (9)¶
Create and manage data streams with input/output configuration.
| Tool | Description |
|---|---|
bf_list_all_datasets | List all datasets (flat list) |
bf_list_datasets | List datasets for a tenant |
bf_get_dataset | Get dataset details including input/output config |
bf_create_dataset | Create dataset |
bf_update_dataset | Update dataset configuration |
bf_delete_dataset | Delete dataset |
bf_test_dataset | Test dataset input/output connectivity |
bf_dataset_statistics | Processing stats (records in/out, bytes, errors) |
bf_dataset_parquet_files | List parquet output files |
Proxies (8)¶
Manage proxy instances, configuration, and dataset assignments.
| Tool | Description |
|---|---|
bf_list_proxies | List all proxy instances with config and health |
bf_account_proxies | List proxies for a specific account |
bf_get_proxy_config | Get proxy instance config |
bf_update_proxy_config | Push new config to proxy (applied on next poll) |
bf_proxy_config_history | Config change history |
bf_delete_proxy | Delete proxy registration |
bf_update_dataset_proxy_assignment | Assign proxy to dataset |
bf_account_services | List all service instances for an account |
Transformations (8)¶
Build, test, and deploy data transformation pipelines.
| Tool | Description |
|---|---|
bf_get_transformation | Get active transformation config |
bf_validate_transformation | Syntax check (no execution) |
bf_test_transformation | Test config against sample data |
bf_activate_transformation | Deploy and activate on dataset |
bf_transformation_history | Job history |
bf_transformation_jobs | List transformation jobs |
bf_transformation_stats | Processing statistics |
bf_transformation_schema | Discovered field names and types |
bf_filter_catalog | Available transformation filters with documentation |
Errors (7)¶
Track and resolve processing errors.
| Tool | Description |
|---|---|
bf_list_errors | All errors system-wide (system admin) |
bf_error_stats | Error counts by type, service, status |
bf_account_error_stats | Error stats for a specific account |
bf_list_account_errors | Errors for a specific account |
bf_list_dataset_errors | Errors for a specific dataset |
bf_update_error_status | Resolve or acknowledge an error |
bf_resolve_errors_by_type | Bulk resolve errors by type |
Releases & Upgrades (7)¶
Manage software releases and track upgrade status.
| Tool | Description |
|---|---|
bf_list_releases | List available software releases |
bf_create_release | Create release entry |
bf_update_release | Update release |
bf_delete_release | Delete release |
bf_list_upgrades | Pending upgrades for all services |
bf_list_account_upgrades | Pending upgrades for account |
bf_set_upgrade_status | Set upgrade status for instance |
Users (6)¶
Manage user accounts and access.
| Tool | Description |
|---|---|
bf_list_users | List all users |
bf_get_user | Get user details |
bf_create_user | Create user (email, role, account_id) |
bf_update_user | Update user |
bf_delete_user | Delete user |
bf_toggle_user_active | Enable/disable user |
Services (3)¶
Manage registered service instances.
| Tool | Description |
|---|---|
bf_delete_service | Remove a service instance registration |
bf_update_service_description | Update service instance description |
bf_get_config | Get system configuration |
Audit (2)¶
Review who did what, when.
| Tool | Description |
|---|---|
bf_list_audit_logs | List audit logs |
bf_get_audit_log | Get full audit log entry |
Deployment Generators (4)¶
Generate deployment configurations for different environments. All accept optional parameters: scenario (proxy or full), account_id, api_key, control_url, s3_endpoint, s3_access_key, s3_secret_key, image_registry, image_tag, receiver_url, use_bundled_minio.
| Tool | Description |
|---|---|
bf_generate_docker_compose | Docker Compose files with configs |
bf_generate_helm_values | Kubernetes Helm values.yaml |
bf_generate_systemd | Systemd install script with .service files |
bf_generate_standalone | Standalone run script that downloads binaries |
AI-Assisted Deployment¶
Use Claude Code with the MCP server to deploy ByteFreezer end to end — create tenants, generate configs, deploy via SSH or Helm, and verify the pipeline. See Deploy with Claude + MCP for step-by-step instructions.
Examples¶
Check system health¶
Ask your AI assistant:
"Check the health of my ByteFreezer deployment"
It will call bf_health_status and bf_system_stats to give you a summary.
Create a tenant and dataset¶
"Create a tenant called 'production' under my account, then create a syslog dataset for it"
The assistant will use bf_list_accounts to find your account, bf_create_tenant, then bf_create_dataset with the appropriate input configuration.
Debug data flow issues¶
"Show me errors for my test dataset and check if the proxy is healthy"
Uses bf_list_dataset_errors, bf_dataset_statistics, and bf_health_service to diagnose issues.
Generate a deployment¶
"Generate a Docker Compose deployment for a full stack with MinIO"
Calls bf_generate_docker_compose with scenario: full and use_bundled_minio: true, returns ready-to-use files.
Build a transformation pipeline¶
"Show me the schema for my dataset and create a transformation that drops debug-level logs"
Uses bf_transformation_schema to discover fields, bf_filter_catalog to find the right filter, bf_test_transformation to validate, then bf_activate_transformation to deploy.