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:

1. echo_message - Echoes back any JSON input
2. why_are_we_yelling - Converts text to UPPERCASE
3. query_json - Processes JSON with jq filters
4. 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

Register a new 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:

1. Edit containers/server.js to handle new input patterns
2. Add new tool definitions to migrations/0002_seed_example_tools.sql
3. 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

1. 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

2. Deploy Worker and Containers:

npm run deploy

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

3. 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

• Cloudflare Containers Docs
• Model Context Protocol
• mcp-lite GitHub
• Containers Examples

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