Durable Thinking README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Durable Thinking listing page.
Durable Thinking
Persistent sequential thinking for MCP clients, on Cloudflare Workers.
The canonical Sequential Thinking server keeps thoughts in process memory and forgets them when the process exits. This one gives them somewhere durable to live — the same reasoning model (adjustable totals, continuation, revision, branching), just persisted instead of discarded. Every step is written to a SQLite-backed Cloudflare Durable Object, addressable later by an unguessable id, and — for clients that support MCP Apps — rendered as a card of its own.
It's a single-user deployment: one GitHub account allowed through the sign-in gate, one bearer token for header-capable clients, one private store, and a deploy-button template for standing up your own copy.
What a thought looks like
A normal sequentialthinking call stays readable in any client:
The structured result stays deliberately small — the thought itself isn't repeated in it:
MCP Apps-capable hosts get the same thought delivered separately, to a UI resource: ui://sequential-thinking/process.html. Hosts render one card per tool call, so the App leans into that instead of fighting it — each card shows only its own thought, no polling, no state shared with other cards, and the chat transcript itself becomes the timeline. When the sequence finishes (nextThoughtNeeded: false), that last card loads the full stored history and renders the entire process at once: every thought in order, branches and revisions marked, earlier steps collapsed and expandable.
The App is one self-contained HTML document — no external scripts, fonts, or network calls. It reaches history only through the host's authenticated MCP connection. Clients without MCP Apps support just get the plain text result.
Thoughts aren't retransmitted on every write, either — only the current one. The model reloads earlier ones on purpose, with get_thought_history.
Capability-scoped history
There's no tool to list sequences, and none is coming. The sequenceId handed back from the first call is the only way in — long enough to be unguessable, and the sole credential its history checks. Hold the id, read the sequence; don't have it, and it doesn't exist for you.
That's what lets one deployment serve many clients and sessions at once without any of them seeing each other's reasoning: authentication gets you in the door, the sequence id gets you into a room.
Tools
sequentialthinking
Persists one reasoning step. Omit sequenceId on the first call; carry the returned id through every continuation.
Branch by pairing branchId with branchFromThought (forking from the main path) or adding branchFromBranchId (forking from inside another branch), then keep passing that branchId on later steps. Revise with isRevision: true and revisesThought.
Thought numbers are scoped to the branch writing them, so two branches can each have their own thought 3 — a reference resolves against the branch being written, then its ancestors back to each fork point, nearest scope wins.
Two edge cases are accepted and flagged in the result rather than treated as errors: continuing a sequence after a thought said nextThoughtNeeded: false just reopens it, and reusing a thought number on the same branch resolves later references to its newest occurrence.
get_thought_history
Returns full-text history, oldest-first and paginated — pass nextCursor back as cursor to continue (cursor values are opaque; don't compute them). Pass branchId to restrict the page to one branch; sequence.branches lists every branch with its parent and fork point.
delete_thought_sequence
Permanently deletes a sequence and its stored text. Requires confirm: true.
Architecture
The MCP transport is stateless — no Mcp-Session-Id is used as a database key or continuity mechanism. All application state lives in the Durable Object instead, keyed by the sequenceId passed explicitly in tool arguments.
Only text submitted through the public thought argument is ever stored; the server has no access to a model's private or hidden reasoning.
Deploy your own
One click
Deployment requires three secrets: MCP_API_TOKEN (the static bearer — generate at least 32 random bytes), plus GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET from the OAuth app described under GitHub sign-in below.
You'll also need your own OAuth KV namespace — npx wrangler kv namespace create OAUTH_KV, then put its id in wrangler.jsonc (namespace ids aren't secrets).
You'll get three endpoints:
GitHub sign-in
Browser-based clients authenticate by signing in to GitHub; access is granted only to allowlisted accounts.
- Create an OAuth App under GitHub Developer settings — Homepage URL
https://<worker-host>, callback URLhttps://<worker-host>/callback. - Store its credentials as Worker secrets:
npx wrangler secret put GITHUB_CLIENT_ID, thenGITHUB_CLIENT_SECRET. - Set the allowlist:
npx wrangler secret put ALLOWED_GITHUB_LOGIN— one or more comma-separated GitHub logins, matched case-insensitively. Empty or missing fails closed: nobody can complete authorization. It's a secret rather than awrangler.jsoncvar so continuous deploys never overwrite it.
The sign-in flow reads only your GitHub identity, checks it against the allowlist, and discards the GitHub token. Authorization is keyed to the immutable account id, not the renameable login.
Continuous deployment
GitHub Actions runs npm run verify on every pull request and every push to main; a verified push to main deploys the Worker with Wrangler. Deploys never overlap, and the deploy job skips gracefully when its credentials are absent — as in a fork.
Set these under Settings → Secrets and variables → Actions:
CLOUDFLARE_API_TOKEN— Workers Scripts: Edit permission;CLOUDFLARE_ACCOUNT_ID— the account that owns the Worker.
These authorize deployment and are separate from the runtime secrets above.
Registry publication
GitHub Releases publish Durable Thinking metadata to the official MCP Registry through .github/workflows/publish-mcp.yml. The job uses GitHub OIDC, so it needs id-token: write but no long-lived Registry credential. server.json advertises a required worker_host variable and the complete https://{worker_host}/mcp-compat URL, reflecting the project's deploy-your-own model rather than directing strangers to one private deployment.
This repository is deliberately not published to npm. Its package.json describes a Cloudflare application and has no bin or local stdio transport; an npm artifact would not give clients an installable MCP server. If a supported local runtime is added later, npm Trusted Publishing can be introduced then, with a real executable, package ownership metadata, and provenance.
Smithery URL publication is also separate from the release workflow. Smithery expects one concrete upstream URL, while each Durable Thinking owner deploys a private Worker with a GitHub allowlist. Add Smithery only if the service gains a multi-user hosted access model or Smithery supports the deploy-your-own URL template directly.
By hand
Requirements: Node.js 22+, a Cloudflare account with Workers and Durable Objects enabled, Wrangler authenticated.
Copy the result into an uncommitted .dev.vars (see .dev.vars.example for the GitHub fields):
When ready to ship:
Configuration
wrangler.jsonc declares the Durable Object and KV bindings. Optional Worker variables, set via Cloudflare or a local .dev.vars:
| Variable | Default | Purpose |
|---|---|---|
THOUGHT_RETENTION_DAYS | 0 | 0 retains sequences until explicit deletion; a positive value enables sliding expiration. |
ALLOWED_HOSTNAMES | automatic | Optional comma-separated host allowlist, for custom domains. |
ALLOWED_ORIGIN_HOSTNAMES | supported web clients and same-host | Optional comma-separated browser-Origin hostname allowlist; setting it replaces the default Claude and ChatGPT web origins. |
There's deliberately no public mode, tenant selector, configurable storage id, thought-logging switch, or automatic recent-history return — one user, one hard-coded Durable Object name: personal. Rotating MCP_API_TOKEN or the OAuth credentials doesn't orphan history; storage identity is independent of both.
Connect your clients
Two doors, one server.
Browser sign-in — for hosted clients that can't send custom headers, including Claude and ChatGPT. Add a custom connector or MCP app pointing at the complete compatibility URL:
Keep the /mcp-compat path: it is part of the protected resource identifier, not an interchangeable routing detail. The compatibility endpoint supports the 2025-era Streamable HTTP protocol used by current hosted clients. The host discovers the OAuth endpoints, dynamically registers its own callback, and opens the Durable Thinking consent page. Continue to GitHub; if your login is on the allowlist, the host receives its own Durable Thinking access and refresh tokens.
The GitHub OAuth App still uses https://<worker-host>/callback, as configured during deployment. That is the Worker's upstream GitHub callback; it is separate from the redirect URI that Claude or ChatGPT registers with the Worker.
Bearer header — for CLIs and anything header-capable:
An exact token match routes straight to the MCP handler; the OAuth machinery never sees it.
Use /mcp only for clients that explicitly support MCP 2026-07-28. Use /mcp-compat for current hosted web clients and other 2025-era Streamable HTTP clients.
OAuth troubleshooting
The browser consent step does not depend on third-party cookies. If connection fails, check the protocol surfaces in order:
POST /mcp-compatwithout credentials must return401and aWWW-Authenticateheader whoseresource_metadataURL ends in/oauth-protected-resource/mcp-compat.- That metadata document's
resourcevalue must exactly equalhttps://<worker-host>/mcp-compat. /.well-known/oauth-authorization-servermust advertise/authorize,/token,/register, and S256 PKCE support.- If
ALLOWED_ORIGIN_HOSTNAMESis set, include the hosted client's hostname. Leaving it unset permits the server's own host plus the supported Claude and ChatGPT web origins; unrelated origins remain rejected. - The consent page's CSP must allow
form-action 'self' https://github.com. Earlier deployments allowed only'self', so Chrome accepted the form POST but blocked its redirect to GitHub.
Worker logs use fixed stage and reason fields without recording authorization codes, state values, access tokens, client secrets, or thought text.
Retention and privacy
Thought text can contain private prompt context, copied credentials, personal information, or uncertain conclusions. The server treats it accordingly:
- every MCP request authenticates — an issued OAuth token or the bearer secret;
- thought text is never logged;
- one private Durable Object, owned by you alone;
- the App's CSP blocks all outbound network access;
- sequences can be deleted explicitly, and are retained indefinitely by default.
CORS and MCP App visibility metadata are not authentication controls — keep the bearer token secret.
Development
src/ui/thought-process.html is the App's source of truth; Wrangler imports it as a text module via the rule in wrangler.jsonc.
License
MIT. See LICENSE and NOTICE.