Durable Thinking MCP server
Commit Nov 7, 2026Provides persistent sequential thinking for MCP clients by storing reasoning steps in a SQLite-backed Cloudflare Durable Object.
Also known as linxule/durable-thinking, durable-thinking
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 3.2.0
- Last commit
- Nov 7, 2026
- License
- MIT
What is Durable Thinking MCP?
Durable Thinking provides persistent sequential thinking for MCP clients by storing reasoning steps in a SQLite-backed Cloudflare Durable Object.
Summary generated from the project's README
About Durable Thinking MCP server
Durable Thinking provides a way for MCP clients to maintain persistent reasoning steps across sessions. While standard sequential thinking servers lose data when a process exits, this implementation uses a SQLite-backed Cloudflare Durable Object to store every thought. This allows a reasoning model to continue, revise, or branch its logic even after a connection is closed. It is designed as a single-user deployment where a developer hosts their own instance on Cloudflare Workers.
Users can connect via browser-based GitHub sign-in for hosted clients like Claude or ChatGPT, or use a static bearer token for CLI tools and header-capable clients. The server manages state through a unique sequenceId, ensuring that reasoning histories remain private and unguessable. It includes specific tools like sequentialthinking for persisting steps, get_thought_history for retrieving paginated logs, and delete_thought_sequence for permanent removal of data.
What you can do with it
- 1Persist long-running reasoning chainsA developer can maintain a continuous thought process that survives client restarts by using the sequenceId to resume a session.
- 2Branch and revise complex logicAn AI client can explore different reasoning paths by forking from a specific thought or correcting previous steps.
- 3Secure private reasoning storageUsers can ensure their reasoning steps are only accessible to them by using an unguessable sequence ID and GitHub authentication.
Written from the project's README. Every use case is checked against a quote from it.
How to install Durable Thinking MCP
Durable Thinking gives each account its own endpoint, so there is no address to copy here. Get yours from the provider, put it in place of the part in braces, and add it to your client as a remote server.
https://{worker_host}/mcp-compat
Configuration
MCP_API_TOKEN
| Name | Description | |
|---|---|---|
| MCP_API_TOKEN | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelinxule/durable-thinking is public and reachablegithub.com/linxule/durable-thinking ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/linxule/durable-thinking ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeEndpoint did not answer initialize: unreachableFinding
README
View on GitHubDurable 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:
Thought 3/5
A Durable Object keeps the application history persistent while the MCP HTTP
transport remains stateless.
Sequence: seq_... · 3 thoughts stored
The structured result stays deliberately small — the thought itself isn't repeated in it:
{
"sequenceId": "seq_...",
"thoughtNumber": 3,
"totalThoughts": 5,
"thoughtHistoryLength": 3
}
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.
thought
nextThoughtNeeded
thoughtNumber
totalThoughts
sequenceId?
isRevision?
revisesThought?
branchFromThought?
branchId?
branchFromBranchId?
needsMoreThoughts?
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
MCP client
│
│ POST /mcp or /mcp-compat
│ OAuth access token or static bearer token
▼
Cloudflare Worker
│
│ static token → straight to the MCP handler
│ anything else → workers-oauth-provider validation
│ fresh MCP server for each request
▼
ThoughtStore Durable Object: "personal"
│
▼
SQLite tables for sequences, thoughts, and branches
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.
openssl rand -hex 32
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:
https://<worker>.<account>.workers.dev/mcp
https://<worker>.<account>.workers.dev/mcp-compat
https://<worker>.<account>.workers.dev/healthz
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.
npm install
npm run verify
npm run secrets # generates a local token
Copy the result into an uncommitted .dev.vars (see .dev.vars.example for the GitHub fields):
MCP_API_TOKEN=<generated token>
npm run dev
When ready to ship:
npx wrangler secret put MCP_API_TOKEN
npm run deploy
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:
https://<worker-host>/mcp-compat
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:
Authorization: Bearer <MCP_API_TOKEN>
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
npm run check:app # validates the self-contained MCP App and protocol surface
npm run check:contract # guards the compact tool and visibility contract
npm run check:registry # guards the official Registry manifest and version sync
npm run typecheck # Worker and test TypeScript projects
npm run test # Durable Object, auth, routes, and App invariants
npm run build # Wrangler dry run
npm run verify # all checks above
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.
src/index.ts Worker routes, authentication boundary, MCP handler
src/server.ts tools, compact return shapes, MCP App resource
src/thought-store.ts SQLite Durable Object implementation
src/oauth.ts GitHub sign-in and consent flow around the OAuth provider
src/ui/thought-process.html per-thought MCP App card with final process view
src/auth.ts fixed personal bearer authentication
src/model.ts storage commands and records
test/ Worker, storage, auth, and App tests
License
MIT. See LICENSE and NOTICE.
Durable Thinking MCP questions
How does the server handle reasoning history?
It uses a SQLite-backed Cloudflare Durable Object to ensure reasoning steps are persisted and addressable via a unique sequence ID rather than being lost when a process exits.
Can I deploy my own instance?
Yes, there is a deploy-button template for Cloudflare Workers that allows you to set up your own private, single-user deployment.
How is access controlled for different users?
Access is managed through GitHub OAuth for browser-based clients and bearer tokens for header-capable clients, ensuring reasoning sequences remain private.