BYOB MCP Server 🚀

Bring Your Own Binary: A dynamic MCP server built on Cloudflare Workers, Containers, and D1.

Enables AI agents to discover and invoke containerized tools registered at runtime—no redeployment needed.

Quick Start

# Install dependencies npm install # Start local dev server npm run dev # In another terminal, test the API bash test-api.sh # Deploy to production npm run deploy

What This Is

A proof-of-concept demonstrating:

✅ Dynamic Tool Registry - Tools stored in D1, queried by MCP server
✅ Containerized Execution - Each tool runs in isolated Cloudflare Container
✅ MCP Protocol - AI agents discover tools via Model Context Protocol
✅ HTTP Registration API - Register new tools without redeploying
✅ Scale-to-Zero - Containers only run when tools are invoked

Architecture

AI Agent (Claude) ──[MCP]──> Cloudflare Worker ──[HTTP]──> Universal Container │ (ToolRunner) └──[SQL]──> D1 Registry Supports: • Echo • Uppercase • JQ • Git Clone

Pre-Built Demo Tools

All four tools run in a single universal container:

echo_message - Echoes back any JSON input
why_are_we_yelling - Converts text to UPPERCASE
query_json - Processes JSON with jq filters
summarize_repo_readme - Clones a GitHub repo and summarizes its README

API Endpoints

GET /

Health check and server info

GET /api/tools

List all registered tools

POST /api/register-tool

{ "name": "my_tool", "description": "What this tool does", "containerClass": "echo", "schema": { "type": "object", "properties": { "input": {"type": "string"} } } }

POST /mcp

MCP protocol endpoint (connect your AI agent here)

Example: Register a Tool

curl -X POST http://localhost:8787/api/register-tool \ -H "Content-Type: application/json" \ -d '{ "name": "whisper", "description": "Echoes message in lowercase", "containerClass": "toolrunner", "schema": { "type": "object", "properties": { "message": {"type": "string"} }, "required": ["message"] } }'

Connect to Claude Desktop

Edit your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "byob-server": { "url": "http://localhost:8787/mcp" } } }

Restart Claude Desktop, then ask:

"What tools do you have available?"
"Can you echo the message 'Hello BYOB!'?"
"Use why_are_we_yelling with text: hello world"
"Summarize the README from https://github.com/fiberplane/mcp-lite"

Documentation

PROJECT_SUMMARY.md - High-level overview
HACKATHON.md - Full architecture and setup guide
DEMO.md - Step-by-step demo script
CLAUDE.md - Development instructions (for AI assistants)

Project Structure

├── src/ │ ├── index.ts # Main Worker + MCP server │ ├── containers.ts # Container class definitions │ └── types.ts # TypeScript interfaces ├── containers/ │ ├── Dockerfile # Universal container image │ ├── server.js # Multi-tool HTTP server │ └── README.md # Container documentation ├── migrations/ │ ├── 0001_initial_schema.sql │ └── 0002_seed_example_tools.sql └── wrangler.jsonc # Cloudflare configuration

Adding New Tools

Since all tools use the same universal container, adding new tools is simple:

Option 1: Via API (No redeployment needed)

curl -X POST http://localhost:8787/api/register-tool \ -H "Content-Type: application/json" \ -d '{"name":"my_tool", "description":"...", ...}'

Option 2: Extend the Container

To add new operation types:

Edit containers/server.js to handle new input patterns
Add new tool definitions to migrations/0002_seed_example_tools.sql
Redeploy

The single container approach keeps things simple for demos while still demonstrating the BYOB architecture.

Technology Stack

Runtime: Cloudflare Workers (V8 Isolates)
MCP: mcp-lite (not @modelcontextprotocol/sdk)
Web Framework: Hono
Database: Cloudflare D1 (SQLite)
Containers: Cloudflare Containers (Durable Objects)
Schema: Zod + JSON Schema

Deployment

Local Development

npm run dev # Server runs on http://localhost:8787

Production Deployment

Run migrations on remote database:

npx wrangler d1 execute byob-tools-registry --remote \ --file=./migrations/0001_initial_schema.sql npx wrangler d1 execute byob-tools-registry --remote \ --file=./migrations/0002_seed_example_tools.sql

Deploy Worker and Containers:

npm run deploy

Note: First deployment takes 2-5 minutes to build Docker images.

Update Claude Desktop config with your production URL:

{ "mcpServers": { "byob-server": { "url": "https://byob-mcp-server.YOUR_ACCOUNT.workers.dev/mcp" } } }

Testing

# Automated API tests bash test-api.sh # Manual health check curl http://localhost:8787/ # List tools curl http://localhost:8787/api/tools | jq # Test MCP protocol curl -X POST http://localhost:8787/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Key Features

Dynamic Discovery

Tools registered in D1 appear immediately to all connected AI agents—no redeployment required.

Secure Isolation

Each container runs in an isolated sandbox with resource limits and ephemeral storage.

Serverless Scale

Containers scale to zero when idle. Pay only for actual tool invocations.

Standard Interface

All containers expose POST /execute endpoint accepting/returning JSON.

Limitations

Container classes must be defined at deploy time in wrangler.jsonc. True runtime BYOB would require automatic Worker rebuild/redeploy when new containers are registered.

Workaround: Multiple logical tools can share the same container class, allowing significant flexibility without redeployment.

Resources

License

MIT - Built for hackathon demonstration

Contributing

This is a hackathon prototype. For questions or suggestions, open an issue!

Built with ☁️ Cloudflare Workers | 🐳 Containers | 🗄️ D1 | 🤖 MCP

BYOB MCP Server