Provides tools for reading and writing files, creating branches, and opening pull requests on GitHub repositories, using a dedicated GitHub App for authentication and access.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Capsid search for documents about deployment"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Capsid is a Model Context Protocol (MCP) server and control plane for AI coding agents. It runs as a single Cloudflare Worker and provides four functions to the agents that connect to it:
a versioned knowledge base of project documents, stored in D1 and searchable by keyword and by meaning;
a work queue of signed task descriptions, from which agents claim and complete work;
per-agent credentials with explicit scopes, enforced at a single authorization point;
mediated access to GitHub repositories through a GitHub App, with a record of each agent's reported outcome alongside the outcome GitHub confirms.
The repository contains the source of one production deployment, operated by its owner and the co-owners listed in CO_OWNER_EMAILS. It is published under the MIT licence for reference. It is not a hosted service and is not supported for third-party use; Installation describes how to run a separate instance.
The public system explorer at capsid.dustinedwards.info, generated daily from Capsid's public data.
Related MCP server: MCP Knowledge Server
Capsid is written in TypeScript and deployed as one Cloudflare Worker. It uses the following bindings:
Binding | Type | Purpose |
| D1 | Documents, document versions, jobs, agents, namespaces, outcomes and the audit log. Full-text search uses SQLite FTS5. |
| KV | Cached GitHub installation tokens, switches and short-lived state. |
| KV | OAuth grants and client registrations. |
| R2 | Daily database exports and the Markdown mirror of every document. |
| AI Search | A derived semantic index of the documents, used for hybrid search. D1 remains the source of record. |
| Static assets | The built Capsid Portal ( |
The Worker answers on two hosts, each restricted to its own set of paths:
MCP host (mcp.dustinedwards.info): the MCP endpoints, OAuth sign-in, agent and operator routes under /ops/, and the public read-only documents. The permitted paths are listed in src/mcp-host.ts.
Portal host (portal.dustinedwards.info): the Capsid Portal, the administrative web application. See src/portal-host.ts.
The system explorer at capsid.dustinedwards.info is a separate, assets-only Worker built from explorer/. It is prerendered from Capsid's public documents and makes no requests to Capsid at read time.
Caller | Mechanism |
Owner and co-owners, through an MCP client or the Portal | Cloudflare Access for SaaS (OIDC), issued as an OAuth access token by |
Agents and scheduled clients | A per-agent bearer key on |
Capsid, towards GitHub | A GitHub App. The Worker signs an RS256 JWT and exchanges it for a short-lived installation token; no long-lived GitHub token is stored. |
Every caller resolves to an agent record with a name, a set of scopes and an audit identity. Authorization is checked in one function, checkScope in src/scope.ts.
Three Cron Triggers are declared, and their expressions are defined once in src/index.ts:
Schedule (UTC) | Task |
| The tick: site watcher, auto-merge evaluation, merge-state sweep, search indexing, phone alerts, the daily email digest, and the daily build of the public model and statistics. |
| Database backup to R2, followed by pruning of old document versions and audit rows. |
| Weekly skills refresh, which runs on one configured day and posts a job when a model's prompting guide has changed. |
A document is a row in D1 identified by namespace and path, with a title, a Markdown body, a type, a status and tags. A namespace corresponds to one project and maps to one or more GitHub repositories; that mapping is also the boundary for repository access. Document types include core, concept, decision, spec, protocol, procedural, task and reference (docs/schema.md).
Every overwrite or delete stores the previous body in document_versions and writes a row to audit_log. Search combines FTS5 keyword matching with semantic matching from an AI Search index. The index is filled from D1 by the five-minute tick, and every semantic result is re-checked against D1 before it is returned.
An agent's scopes have five axes: namespaces, repos, tools, grants (read, or read and write) and flags. Flags control operations with a wide effect, such as merging (can_merge), committing directly to a default branch (can_direct_write), dispatching workflows (can_dispatch) and writing protected paths (can_touch_protected). A new agent receives read access to its named namespaces and no flags. Scopes that fail to parse resolve to no access. The required grant for each tool is declared in TOOL_GRANTS (src/scope.ts), and a tool absent from that table requires the write grant. See docs/auth.md.
A job consists of a title and a body; the body is the complete prompt an agent executes. Bodies are signed when posted, and a claim verifies the signature first, so a body altered outside the queue's own edit action is rejected. The lifecycle is post, claim, then complete, fail, block or resume. A job that reaches an operation requiring a person (a push, a deploy, a secret, a live migration or a merge) is blocked with the exact command to run. Capsid assigns each job a kind and a recommended model and effort (src/model-routing.ts).
Capsid can start a Claude Code cloud session for a queued job by firing a saved Claude Code routine (docs/routines.md). When an agent completes a job, it names the pull request that carries the work. Capsid then reads that pull request from GitHub and stores the verified state beside the agent's claim, so the two can be compared (docs/work-queue.md).
Repository tools resolve the target repository from the namespace mapping and check the resolved repository against the caller's repos axis (docs/repo-access.md). Agents open pull requests; merging requires the can_merge flag.
Automatic merging is governed by a policy document that must be signed by the administrator before it has any effect; an unsigned policy, or one edited after signing, authorizes nothing. When enabled, the tick merges only pull requests that pass every check in the policy. Certain paths, including migrations, workflows, lockfiles and authentication code, are always refused automatic merging (docs/autonomy.md). Both automatic merging and the overnight run (docs/overnight.md) are disabled in a new installation.
The Portal is a single-page application in dashboard/, served by the Worker as static assets and restricted to the administrator's Cloudflare Access session. It presents items awaiting the owner, site health, the job queue, open pull requests, deploys, agents, activity and backups, and exposes the administrative controls defined in src/controls.ts (docs/portal.md).
Portal Health view, rendered from sample data.
Portal job queue with a job's detail drawer open, rendered from sample data.
The watcher, which runs on the tick, reads each registered site's health route, CI status, deploys and live responses (docs/health-format.md, docs/live-checks.md). Search performance is read from Google Search Console and Bing Webmaster Tools (docs/search-console.md, docs/bing-webmaster.md).
Claude Code sessions can send hook events to /ops/hooks and OpenTelemetry metrics to /ops/otlp/v1/*. Capsid keeps per-session summaries and per-job cost and token totals; it does not store prompts, responses or tool content (docs/hooks.md, docs/telemetry.md).
Once a day the Worker builds a public system model and a set of aggregate statistics, after a privacy filter, and serves them without authentication (docs/public-data.md). Current figures are available at mcp.dustinedwards.info/public/stats/v1.json. The system explorer is built from these documents (explorer/README.md).
D1 Time Travel provides 30-day point-in-time recovery. In addition, the daily backup writes one JSON export per table and a Markdown mirror of every document to R2, and the exports are mirrored to a private repository outside the Cloudflare account. A scheduled workflow rehearses a restore (docs/backups.md). Rolling back a faulty deploy is described in docs/rollback.md.
Capsid serves 22 tools over two MCP servers. The count is derived from TOOL_GRANTS by src/counts.ts, and the registrations are in src/tools/surface.ts. Most tools take an action argument that selects one operation.
Capsid (/mcp, /ops/mcp): 14 tools for project work.
Tool | Grant | Function |
| read | Session briefing for a namespace. |
| read | List, glob or full-text search documents; list reachable namespaces. |
| read | Read a document, its versions or its edges. |
| write | Create, change, restore or move a document. |
| write | Delete a document, retaining its last version. |
| per action | Gather, finalize and report on a namespace's documents (docs/consolidation.md). |
| read | List directories, read files and search code in a mapped repository. |
| read | Branches, tags, pull requests, history, CI runs, live site checks and search-console data. |
| write | Write or delete a file, or create a branch. |
| write | Open a pull request or comment on one. |
| write | Merge or close a pull request, delete a branch, tag a commit or publish a release. |
| write | Dispatch a workflow or rerun failed jobs. |
| per action | The work queue lifecycle. |
| read | Capsid status per namespace: queue, breaker, maintenance and items awaiting the owner. The name is retained from a removed feature. |
Capsid Admin (/mcp/admin, /ops/mcp/admin): 8 tools, available to the administrator identity only.
Tool | Grant | Function |
| admin read | Items awaiting the owner across every namespace. |
| admin | Register, remap or delete a namespace. |
| admin | Mint, revoke and re-scope agent credentials. |
| admin read | Agent claims beside verified outcomes. |
| admin read | Watcher state, Cloudflare Access and Email Routing configuration, Workers Builds. |
| admin | Preview and perform administrative controls with a single-use token. |
| admin | Operator keys, policy signing, the job breaker and the overnight switch. |
| admin | Mint a site key and install it on the site Worker. |
Adding a tool requires a recorded ruling (CLAUDE.md, rule 1).
The router is defaultHandler in src/routes.ts. The principal routes are:
Route | Authentication | Purpose |
| OAuth | MCP over Streamable HTTP for the owner and co-owners. |
| Bearer key | MCP for agents and scheduled clients. |
| None | OAuth sign-in and discovery. |
| Bearer key | Claude Code hook events and telemetry. |
| Bearer key | Items awaiting the owner, per application. |
| None | Deploy provenance and a store probe; returns 503 when D1 or FTS5 fails. |
| None | Public system model, statistics and code maps. |
| Access session | The Capsid Portal and its API. |
The complete list, including signed backup and benchmark routes, is in docs/auth.md.
Path | Contents |
| Worker source. |
| D1 schema migrations, applied in order. |
| The Capsid Portal (Vite) and its Playwright tests. |
| The public system explorer, a separate assets-only Worker. |
| The hand-written public system model and its JSON Schema. |
| Deploy, agent minting, backup and verification scripts. |
| Unit tests and lint checks. |
| Integration tests run in workerd through |
| Reference documentation. |
| Template for the Worker configuration. The real |
An installation requires a Cloudflare account and a GitHub App. The procedure is given in full in docs/bootstrap.md, section 10. In outline:
Install dependencies with npm install. Node.js 26.11.1 or later is required.
Create a D1 database, two KV namespaces and an R2 bucket with Wrangler.
Copy wrangler.jsonc.example to wrangler.jsonc and enter the resource identifiers. APP_KV and OAUTH_KV must be different namespaces.
Apply the migrations: npx wrangler d1 migrations apply capsid --remote.
Create a Cloudflare Access for SaaS (OIDC) application and a GitHub App, and set the required secrets.
Run npm run check and npm run deploy.
Add https://<worker-host>/mcp as a custom connector in the MCP client.
wrangler.jsonc, .dev.vars, .env, keys and real document content must never be committed. Optional features, including site monitoring, Cloudflare reads, phone alerts and automatic merging, remain inactive until configured.
Command | Purpose |
| Type-check the Worker. |
| Unit tests. |
| Integration tests in workerd. |
| Lint checks, including documentation drift. |
| Build the Portal and enforce its size budget. |
| Portal browser tests (Playwright). |
| Serve the Portal locally against sample data. |
| Verify the deployed Worker. |
The full pre-push sequence is in docs/bootstrap.md. Continuous integration runs these checks on every pull request, and a merge to master deploys to production.
Setup and access
docs/bootstrap.md: installation, agent minting, switches and pre-push checks.
docs/auth.md: authentication, scopes, roles, co-owners and endpoints.
docs/repo-access.md: the GitHub App and repository resolution.
docs/hooks.md: Claude Code hook events.
docs/telemetry.md: session and job telemetry.
Jobs and agents
docs/work-queue.md: the job lifecycle, signing and recorded evidence.
docs/routines.md: starting cloud sessions through routines.
docs/autonomy.md: automatic merging and pre-approved gates.
docs/overnight.md: the overnight plan and morning digest.
docs/bench.md: the paired comparison run in capsid-bench.
Sites and public data
docs/portal.md: the Capsid Portal.
docs/health-format.md: the health route format.
docs/live-checks.md: checks against deployed sites.
docs/search-console.md: Google Search Console data.
docs/bing-webmaster.md: Bing Webmaster Tools data.
docs/public-data.md: the public model, statistics and code maps.
explorer/README.md: the system explorer.
Data and recovery
docs/schema.md: document types and database tables.
docs/consolidation.md: namespace maintenance and destructive writes.
docs/backups.md: backup contents and restore procedure.
docs/rollback.md: reverting a deploy.
MIT. See LICENSE. Citation metadata is in CITATION.cff.
This server cannot be deployed
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloudflare Workers MCP server: agent-memory
Cloudflare Workers MCP server: agent-workflow-engine
Cloudflare Workers MCP server: api-landing