MCP Server

The bext companion includes a built-in Model Context Protocol (MCP) server that enables AI agents to manage your bext infrastructure autonomously.

What is MCP?

MCP is an open protocol that lets AI models (Claude, etc.) call tools and read resources from external systems. The bext companion exposes 49 tools covering deployment, configuration, data management, security, and observability — everything an agent needs to manage your apps.

Quick Start

Add the bext companion as an MCP server in your Claude Code configuration:

{
  "mcpServers": {
    "bext": {
      "command": "bext-companion",
      "args": ["--mcp"]
    }
  }
}

Once connected, Claude can deploy, rollback, manage secrets, query databases, and monitor your infrastructure through natural conversation.

Available Tools (49)

Deploy & Fleet Management

Tool	Description
`deploy`	Deploy an application to an instance
`rollback`	Rollback to previous version
`promote_canary`	Promote canary deployment to full traffic
`fleet_deploy`	Deploy to multiple instances simultaneously
`deploy_history`	View recent deployment records

Instance Management

Tool	Description
`list_instances`	List all registered bext instances
`instance_overview`	Full instance dashboard (health, metrics, deploys)
`instance_health`	Current health status

Application Management

Tool	Description
`list_apps`	List apps on an instance
`add_app`	Register a new application
`remove_app`	Remove an application
`list_domains`	List configured domains
`add_domain`	Add a domain to an app
`remove_domain`	Remove a domain

Secrets & Configuration

Tool	Description
`list_secrets`	List secret names (not values)
`set_secret`	Set an environment variable
`delete_secret`	Delete a secret
`read_config`	Read bext.config.toml
`reload_config`	Hot-reload server configuration

Data Management

Tool	Description
`db_query`	Execute read-only SQL queries
`db_execute`	Execute write SQL (INSERT/UPDATE/DELETE)
`kv_get`	Get a value from the KV store
`kv_set`	Set a key-value pair with optional TTL
`kv_delete`	Delete a key
`kv_list`	List keys by prefix

Durable Queues

Tool	Description
`queue_push`	Push a job onto a queue
`queue_pull`	Pull pending jobs
`queue_ack`	Acknowledge completed jobs

Cache

Tool	Description
`cache_stats`	ISR cache hit rates and sizes
`cache_invalidate`	Purge cached pages by tag or path

Realtime Pub/Sub

Tool	Description
`realtime_publish`	Publish a message to a topic
`realtime_stats`	Connection and topic statistics

Security (WAF)

Tool	Description
`waf_stats`	Blocked requests and rule hits
`waf_rules`	List rules and their status
`waf_toggle_rule`	Enable or disable a WAF rule

Scheduled Tasks

Tool	Description
`list_tasks`	List cron tasks
`create_task`	Create a scheduled task
`cancel_task`	Cancel a task

Backup & Storage

Tool	Description
`backup_create`	Create a backup
`backup_list`	List available backups
`backup_restore`	Restore from backup

Observability

Tool	Description
`fetch_logs`	Recent log entries
`metrics_overview`	Instance metrics
`run_conformance`	Run conformance test suite

Plugins & Flows

Tool	Description
`list_plugins`	Installed server plugins
`install_plugin`	Install a plugin
`remove_plugin`	Remove a plugin
`list_flows`	Durable workflow executions
`flow_stats`	Workflow statistics

Resources

The MCP server exposes readable resources that agents can reference:

- bext://instance/{id} — Full instance overview (health, metrics, config, recent deploys)

- bext://deploy-history — Recent deployment records across all instances

Security

The MCP server validates all inputs:

- SQL queries are length-limited and block destructive DDL (DROP, TRUNCATE)

- Secret names are restricted to alphanumeric + underscore characters

- Plugin paths reject path traversal (..)

- Queue payloads are size-limited (10MB max)

- Cron expressions are validated (5-6 fields required)

- Domain names are format-checked

- Instance IDs are verified against the registry before any operation

- Credentials are never exposed — resource responses strip sensitive fields

- Request size is bounded — stdin reads are capped at 2MB per line

Example: Agent-Driven Deployment

You: Deploy the latest version to staging, run conformance tests, 
     and if the score is above 95%, promote to production.

Claude: I'll handle that step by step.

1. Deploying to staging...
   → deploy(instance_id: "staging-1") 
   ✓ Deployed v1.2.4 in 3.2s

2. Running conformance tests...
   → run_conformance()
   ✓ Score: 98.5% (133 pass, 1 partial, 0 fail)

3. Score is above 95%, promoting to production...
   → fleet_deploy(instance_ids: ["prod-1", "prod-2", "prod-3"], version: "1.2.4")
   ✓ 3/3 instances deployed successfully

All done. v1.2.4 is live on all production instances.

Protocol

The MCP server uses JSON-RPC 2.0 over stdio, compatible with MCP protocol version 2024-11-05. Each request is a single JSON line on stdin; responses are single JSON lines on stdout.