Reference
Architecture
Kyew is an MCP server built on Cloudflare Workers with D1 database, KV storage, Durable Objects for per-user SQLite, and Sandbox containers for isolated code execution.
System Overview
┌──────────────────────────────────────────────────────────────┐
│ MCP Clients │
│ (Claude Code / Claude Desktop / ChatGPT) │
└──────────────────────────────────────────────────────────────┘
│
│ MCP over HTTP (Streamable HTTP)
▼
┌──────────────────────────────────────────────────────────────┐
│ Cloudflare Workers │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Kyew Worker │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Rate │ │ Quota │ │ Metrics │ │ │
│ │ │Middleware│ │ Limit │ │ Check │ │ Logger │ │ │
│ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └────┬────┘ │ │
│ │ └──────────────┴────────────┴─────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────────────────┴──────────────────────────┐ │ │
│ │ │ HTTP Handler │ │ │
│ │ │ (MCP Protocol Handler) │ │ │
│ │ └──────────────────────┬──────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌────────┬────────┬────┴────┬────────┬────────────┐ │ │
│ │ │Memory │ Skill │Inference│Dynamic │Remote MCP │ │ │
│ │ │Module │ Module │ Module │ Tools │ Module │ │ │
│ │ └───┬────┴───┬────┴───┬─────┴───┬────┴────┬──────┘ │ │
│ └──────┴────────┴────────┴─────────┴─────────┴──────────┘ │
└──────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼───────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ Cloudflare │ │ Cloudflare │ │ Cloudflare Sandbox │
│ D1 │ │ KV │ │ (Code Tools) │
│ (Database) │ │ (Cache) │ └──────────────────────┘
└──────────────┘ └──────────────┘
│ ▲
│ │ /internal/db
▼ │
┌──────────────────────┐ ┌─────────────────────┐
│ Remote MCP Servers │ │ UserDataStore DO │
│ (Aggregated) │ │ (Per-User SQLite) │
└──────────────────────┘ └─────────────────────┘
Components
Worker
The main Cloudflare Worker handles:
- HTTP request routing and MCP protocol messages
- Authentication (Google OAuth, API keys, JWT)
- Rate limiting and request logging
- Cron-triggered scheduled tool execution
Modules
Memory Module
- CRUD operations for memories
- Semantic search using embeddings
- Correction and supersession tracking
Skill Module
- Skill lifecycle management (draft → active → deprecated)
- Version control with rollback
- Approval workflow and conflict detection
- System skills (read-only, available to all users)
Inference Module
- Pattern detection algorithms
- Skill generation from memory clusters
- Context matching and suggestions
Dynamic Tools Module
- Custom tool management (5 types: http_proxy, transform, chain, code, skill_backed)
- HTTP proxy execution with template syntax
- Transform evaluation (JSONata)
- Code tool orchestration with sandbox containers
- Connection credential injection
- Scheduling management
Remote MCP Module
- Connects to external MCP servers via Streamable HTTP
- Gateway tool materialization (one tool per server)
- Tool caching with 24-hour staleness check
- Background refresh via
ctx.waitUntil()
Storage
D1 Database
Primary persistent storage for:
- Memories, skills, and skill versions
- Custom tools and connections (encrypted)
- Tasks, change proposals, audit logs
- Remote MCP server configurations
- Shared skills/tools
KV Namespace
Fast key-value storage for:
- Rate limiting counters
- OAuth session tokens
- Metrics data and temporary cache
UserDataStore Durable Object
Per-user SQLite databases for code tools:
- 10 GB storage per user, zero provisioning
- Accessed via
/internal/dbendpoint with HMAC token verification - Code tools use
db.mjshelper for ergonomic queries - Named databases for data isolation between tools
Sandbox Containers
Isolated VM execution for code tools:
- Cloudflare Sandbox (Node.js 20, ESM only)
- Per-user container reuse (sandbox ID:
user-${userId}) - Connection credentials injected as environment variables
- Configurable timeout and memory limits
Data Model
Memories
CREATE TABLE memories (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
observation TEXT NOT NULL,
domain TEXT,
task_type TEXT,
tools_used TEXT, -- JSON array
outcome TEXT,
tags TEXT, -- JSON array
embedding BLOB,
superseded_by TEXT,
created TEXT,
updated TEXT
);
Skills
CREATE TABLE skills (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL, -- 'system' for system skills
name TEXT NOT NULL,
description TEXT,
domain TEXT, -- JSON array
instructions TEXT,
triggers TEXT, -- JSON array
templates TEXT, -- JSON array
source_memories TEXT, -- JSON array
status TEXT DEFAULT 'draft',
user_approved INTEGER DEFAULT 0,
version INTEGER DEFAULT 1,
embedding BLOB,
created TEXT,
updated TEXT
);
Custom Tools
CREATE TABLE custom_tools (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
name TEXT UNIQUE NOT NULL,
description TEXT,
input_schema TEXT, -- JSON
tool_type TEXT,
http_config TEXT, -- JSON
transform_config TEXT, -- JSON
chain_config TEXT, -- JSON
skill_config TEXT, -- JSON
code_config TEXT, -- JSON
status TEXT DEFAULT 'draft',
created TEXT,
updated TEXT
);
Authentication
OAuth Flow
1. Client requests /oauth/authorize
2. Redirect to Google OAuth
3. User authenticates with Google
4. Callback with auth code
5. Exchange code for tokens
6. Create session in KV
7. Return session token to client
Token Validation
Each request is validated:
- Check for MCP session header or API key
- Validate JWT signature
- Check token expiration
- Extract user ID
- Proceed with request
Code Tool Execution
┌──────────────────────────────────────────────┐
│ Kyew Worker │
│ │
│ 1. Receive tool call │
│ 2. Load code tool config │
│ 3. Resolve connections → env vars │
│ 4. Generate DB token (HMAC-SHA256) │
│ 5. Get/create sandbox (user-${userId}) │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ Cloudflare Sandbox Container │ │
│ │ │ │
│ │ 6. Write handler.mjs, runner.mjs, │ │
│ │ db.mjs to /workspace │ │
│ │ 7. Set env vars (connections, DB URL) │ │
│ │ 8. Execute: node /workspace/runner.mjs │ │
│ │ 9. handler.mjs uses db.mjs for SQLite │ │
│ │ 10. Capture stdout (JSON result) │ │
│ │ │ │
│ └────────────────────────────────────────┘ │
│ │ │
│ 11. Parse result │
│ 12. Return to client │
└──────────────────────────────────────────────┘
MCP Aggregation
Remote MCP servers are proxied through Kyew:
┌─────────────┐ ┌─────────┐ ┌──────────────────┐
│ MCP Client │────▶│ Kyew │────▶│ Remote MCP │
│ │ │ Worker │ │ Server A (GitHub) │
│ │ │ │────▶│ Remote MCP │
│ │ │ │ │ Server B (Slack) │
└─────────────┘ └─────────┘ └──────────────────┘
Each connected server materializes as a single gateway tool. The gateway supports three actions: tools (list), search (progressive discovery with full schemas), and call (execute).
Multi-Tenancy
All data is scoped by user ID:
// Every storage operation includes user_id
await storage.createMemory({
user_id: userId, // From auth token
observation: "...",
});
// Queries automatically filter
const memories = await storage.getMemories({
user_id: userId // Only returns this user's data
});
// System skills use a sentinel value
// user_id = 'system' — readable by all, writable by none
Deployment
Infrastructure
- Worker:
memory-alphaon Cloudflare Workers - Database:
memory-alpha-dbon Cloudflare D1 - KV: Multiple namespaces for rate limiting, OAuth, metrics
- Durable Objects:
UserDataStorefor per-user SQLite - Containers: Sandbox for code tool execution
Scheduled Execution
A cron trigger runs hourly to execute scheduled code tools:
- Checks which tools are due based on hour/timezone
- Executes in sandbox with connection credentials
- Sends email summaries if configured
- Auto-pauses after 3 consecutive failures