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#

Status: the MCP server and all 49 tools are implemented, but the headless --mcp launch flag on the desktop binary is still being wired up. Until it ships, the stdio server isn't started by the command below. Track the entrypoint work before relying on this in production.

Once the flag lands, 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#

Instance Management#

Application Management#

Secrets & Configuration#

Data Management#

Durable Queues#

Cache#

Realtime Pub/Sub#

Security (WAF)#

Scheduled Tasks#

Backup & Storage#

Observability#

Plugins & Flows#

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.

Related#

• Companion Overview — what else the companion app does
• Download — install the companion before enabling the MCP server
• Capabilities → Scheduled Tasks — scheduled task management the MCP create_task tool targets
• Guides → Durable Flows — background on the workflow runs the list_flows tool exposes
• Operations → Monitoring — metrics and logs surfaced by the MCP observability tools

Links#

• Model Context Protocol — the open protocol specification