# AI chat
Source: https://docs.thinkex.app/concepts/ai-chat
Workspace-aware AI with explicit context.
ThinkEx AI chat is scoped to a workspace. It can reason about selected workspace context, inspect workspace items through tool calls, search the web when configured, and run private Python code in a Cloudflare Sandbox.
## Context Is Explicit
The intended workflow is to select the item, document passage, PDF region, or source material you want the AI to use, then ask your question. That keeps the model grounded in visible workspace context instead of relying on opaque retrieval.
## Tools
The AI tool surface is intentionally named and bounded:
Search, read, create, and update workspace content through workspace access checks and explicit persistence operations.
Search the public web, read rendered pages as Markdown, and extract links through policy-checked public HTTP(S) URLs.
Discover and deepen research sources when the workspace task needs external literature or source discovery.
Run private Python code for calculations, tables, charts, and data analysis in a per-thread Cloudflare Sandbox.
Use explicit time helpers when responses need concrete dates or current timestamps.
## Threads
Each chat thread belongs to a workspace and a user. Multiple threads can exist in one workspace so separate lines of inquiry do not need to share one transcript.
## Optional Services
AI behavior depends on configured services. For local development, missing optional secrets do not stop the app from booting, but the feature that needs that secret will fail or stay disabled when invoked. See [environment](/configuration/environment).
# Workspace items
Source: https://docs.thinkex.app/concepts/items
Documents, files, and folders.
Every piece of workspace content is a workspace item. Items can be opened in tabs, renamed, moved, colored, deleted, selected for AI context, and organized into folders.
## Item Types
A collaborative rich-text document backed by Tiptap, ProseMirror, and Yjs. Documents can be created directly, imported from text-like files, or produced by AI.
Uploaded source material. ThinkEx currently stores PDF and image assets as file items, with office documents converted to PDF and HEIC/HEIF images converted to JPEG.
A container for organizing related items. Folders are part of the workspace item tree and can be opened like any other workspace location.
## Supported Uploads
ThinkEx accepts these upload families today:
| Family | Formats |
| ---------------- | -------------------------------------------------------------- |
| PDFs | `.pdf` |
| Office documents | `.docx`, `.pptx` converted to PDF |
| Images | `.png`, `.jpg`, `.jpeg`, `.webp`, `.heic`, `.heif` |
| Text documents | CSV, TSV, Markdown, code, and plain text imported as documents |
Upload limits are currently 50 files or 100 MB per selection.
## Extraction and Previews
PDFs and images are routed through extraction and preview pipelines so the AI can read them and the UI can render usable previews. The current stack uses Cloudflare Workflows, R2, Workers AI, Firecrawl, and conversion containers depending on the file type and configured secrets.
# Workspaces
Source: https://docs.thinkex.app/concepts/workspaces
The shared container for source material, AI, and collaboration.
A workspace is a bounded collection of items shared with members. Each workspace has its own item tree, tabs, AI chat threads, membership, and invites.
Think of it as the place where the work happens: you keep the actual source material in view, open what you need, and ask AI against the context you choose.
## What Lives in a Workspace
| Surface | Purpose |
| ------- | -------------------------------------------------- |
| Items | Documents, files, and folders |
| Tabs | Open views for active items and workspace surfaces |
| AI chat | Workspace-scoped chat threads and tools |
| Members | Owner, Admin, Editor, and Viewer roles |
| Invites | Email invites and expiring invite links |
## Roles
| Role | Summary |
| ------ | ----------------------------------------------------------------- |
| Owner | Full control, including delete and ownership-level administration |
| Admin | Edits content and manages members below owner/admin level |
| Editor | Edits workspace content and can invite at editor or viewer level |
| Viewer | Read-only access to the workspace |
Viewers can inspect content but cannot mutate workspace items. The app shows view-only affordances when a viewer opens mutation controls.
## Source of Truth
The app stores workspace access, the item tree, relationships, current document checkpoints, and extracted text in Postgres. Original and preview file bytes live in R2. The `WorkspaceRoom` Durable Object coordinates presence, workspace-page deltas, and cleanup; it is not a second database. Clients apply canonical item deltas and refetch the authoritative workspace query after reconnecting or when a full refresh is announced. UI and AI operations go through workspace persistence boundaries rather than writing directly to scattered client state.
# Architecture
Source: https://docs.thinkex.app/configuration/architecture
Current ThinkEx runtime shape.
ThinkEx is a full-stack TypeScript app hosted as a Cloudflare Worker. The frontend is React, TanStack Start, Tailwind CSS, Tiptap, EmbedPDF/PDFium, Yjs, and AI SDK. The backend runs on Cloudflare Workers with Durable Objects, PlanetScale Postgres through Hyperdrive, R2, Workflows, Containers, Workers AI, Images, Browser Run, and Email.
## Runtime Ownership
| Data or behavior | Source of truth |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Auth, users, workspace directory, membership, invites | PlanetScale Postgres through Drizzle and cache-disabled Hyperdrive |
| Workspace item tree, relationships, current document checkpoints, extracted text, revisions | PlanetScale Postgres through Drizzle and cache-disabled Hyperdrive |
| Workspace presence, realtime fanout, cleanup coordination | `WorkspaceRoom` Durable Object |
| Original and preview workspace file bytes | R2 `WORKSPACE_FILES` |
| AI chat threads, transcripts, and attachment bytes | PlanetScale Postgres through Drizzle and cache-disabled Hyperdrive |
| AI chat turn streaming | Plain Worker route (`/ai-chat/threads/:id`) with AI SDK `streamText` |
| Collaborative document sessions | `DocumentSession` Durable Object |
| File extraction | Cloudflare Workflows plus configured providers |
| Document conversion | Cloudflare Containers |
## Code Map
| Area | Path |
| -------------------------------- | ----------------------------------------------------------------------------- |
| Workspace contracts and commands | `src/features/workspaces/contracts.ts`, `src/features/workspaces/operations/` |
| Workspace persistence | `src/features/workspaces/persistence/` |
| Workspace realtime room | `src/features/workspaces/realtime/` |
| AI threads and tools | `src/features/workspaces/ai/` |
| File upload and extraction | `src/features/workspaces/upload/`, `src/features/workspaces/extraction/` |
| Document collaboration | `src/features/workspaces/documents/` |
| Sharing and invites | `src/features/workspaces/members/`, `src/features/workspaces/invites/` |
| Cloudflare bindings | `wrangler.jsonc` |
## Deployment Shape
The public landing page and product app are currently served by the same Worker. Production is routed to `thinkex.app`; staging is routed to `staging.thinkex.app`.
## Public Routes
| Route | Purpose |
| -------------------------------- | --------------------------------------------------------- |
| `/` | Public landing page, redirects signed-in users to `/home` |
| `/login`, `/signup` | Authentication entry points |
| `/home` | Protected workspace home |
| `/workspaces/$workspaceId` | Protected workspace route |
| `/settings` | Protected account settings |
| `/invite/$token` | Workspace invite acceptance |
| `/terms`, `/privacy`, `/cookies` | Public legal pages |
## Integrations
| Integration | Use |
| ------------------- | --------------------------------------------- |
| Better Auth | Sessions, Google sign-in, local guest sign-in |
| AI Gateway / AI SDK | Chat models and title generation |
| Firecrawl | Public web search and URL/PDF extraction |
| LlamaCloud | Document extraction |
| The Context Company | Agent observability export |
| Autumn | AI usage analytics |
| PostHog | Product analytics, feedback, and diagnostics |
Do not run deploy, remote migration, legacy-data, or secret-management commands unless you are intentionally performing release or operations work.
# Deployments
Source: https://docs.thinkex.app/configuration/deployments
CI, staging, and production deployment shape.
ThinkEx deploys from Cloudflare Workers Builds. GitHub Actions only validates pull requests. Deploy, migration, and secret-management commands are operational actions and should not be run casually from a local checkout.
## Branches and Environments
| Environment | URL | Worker | Trigger |
| ----------- | ----------------------------- | ----------------- | ----------------- |
| Production | `https://thinkex.app` | `thinkex` | Push to `main` |
| Staging | `https://staging.thinkex.app` | `thinkex-staging` | Push to `staging` |
## CI
The `CI` workflow runs on pull requests only. It installs with Vite+ and runs check, test, and a staging-shaped build:
```bash theme={null}
vp run ciCheck && vp run ciTest && vp run ciBuildStaging
```
`ciBuildStaging` compiles with `CLOUDFLARE_ENV=staging` so PR CI exercises real Wrangler env flattening. PostHog build secrets are optional for that path (analytics stays off when unset); production deploy still requires the full production PostHog set, including the feedback survey id. Local `vp run verify` stays on the generic `ciBuild` (`build:app`) so contributors without Infisical are unaffected. When changes go through a pull request, the `validate` check must be green before merge.
The separate `React Doctor` workflow runs on pull requests and pushes to `main`. It scans changed React files on pull requests, posts inline diagnostics, and records the React Doctor score without folding those comments into the main Vite+ verification job.
## Deploy
Two Workers Builds configurations watch this repository, one per branch. Each runs a build command, then a deploy command that applies Postgres migrations before shipping the Worker:
| Branch | Build | Deploy |
| --------- | --------------------------- | --------------------------------------------------------------- |
| `main` | `pnpm run build:production` | `pnpm run db:migrate && pnpm run deploy:worker` |
| `staging` | `pnpm run build:staging` | `pnpm run db:migrate:staging && pnpm run deploy:worker:staging` |
`CLOUDFLARE_ENV` is set per configuration in the Cloudflare dashboard, which is why `deploy:worker` takes no `--env` flag. Running it from a local checkout without that variable targets the `thinkex-dev` Worker, not production.
Build variables and secrets (Cloudflare API token, PostHog production set) live in the Workers Builds settings. Each deployment configuration also needs the environment's direct PlanetScale administrative connection string as the build-time `DATABASE_URL`; it is used only by Drizzle Kit and is not a Worker runtime secret. The Worker itself connects with the environment's cache-disabled `HYPERDRIVE` binding and a restricted runtime database role.
## Container Images
Production and staging pin container images to immutable `registry.cloudflare.com` digests (`wrangler.jsonc`), so ordinary deploys never need Docker and Workers Builds can run without a Docker daemon. The top-level config still points at the Dockerfiles for `wrangler dev`.
The Dockerfiles change rarely, so there is no workflow for this. When one does change, rebuild and repin by hand from a machine with Docker:
```bash theme={null}
wrangler containers build ./containers/gotenberg \
--tag thinkex-officepdfconverter-production: --push
wrangler containers images list --filter thinkex-officepdfconverter
```
Copy the digest from the second command into the `containers` blocks for both `staging` and `production` in `wrangler.jsonc`, then push. Both environments intentionally share one image per container.
Remote migrations and deploy commands affect shared environments. Run them only when you are intentionally doing release work.
## Secrets
Runtime and deploy secrets originate in Infisical. Build-time secrets (Cloudflare credentials, PostHog variables) are set in each Workers Builds configuration; runtime secrets declared by the Worker configuration are set on the Worker itself. GitHub only holds what PR CI needs.
Direct workspace uploads additionally require bucket-scoped R2 Object Read & Write credentials in `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`, `R2_ACCOUNT_ID`, and an independent random `WORKSPACE_UPLOAD_TOKEN_SECRET` for completion claims. Configure browser PUT access from the checked-in policies:
```bash theme={null}
wrangler r2 bucket cors set thinkex-workspace-kernel-files-staging --file config/r2/cors.staging.json
wrangler r2 bucket cors set thinkex-workspace-kernel-files --file config/r2/cors.production.json
```
After inspecting existing lifecycle rules, add a one-day expiry for abandoned direct-upload objects in each bucket:
```bash theme={null}
wrangler r2 bucket lifecycle add thinkex-workspace-kernel-files-staging expire-abandoned-workspace-file-uploads workspace_file_uploads/ --expire-days 1
wrangler r2 bucket lifecycle add thinkex-workspace-kernel-files expire-abandoned-workspace-file-uploads workspace_file_uploads/ --expire-days 1
```
CORS `set` replaces the bucket's current CORS policy. Reconcile the checked-in policy with any existing rules before applying it.
# Environment
Source: https://docs.thinkex.app/configuration/environment
Runtime variables, secrets, and optional services.
ThinkEx reads runtime configuration from Cloudflare bindings, environment variables, and local `.dev.vars` files. Infisical is the shared secret source for the core team, but it is not required to run the app locally.
## Required to Run Locally
| Variable | Purpose |
| -------------------- | ----------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Signs auth sessions |
| `BETTER_AUTH_URL` | Canonical local app origin, usually `http://localhost:3000` |
## Optional Secrets
| Variable | Feature |
| ------------------------------------------- | --------------------------------- |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Google sign-in |
| `AI_GATEWAY_API_KEY` | AI chat and title generation |
| `AUTUMN_SECRET_KEY` | AI usage analytics |
| `FIRECRAWL_API_KEY` | Web search and URL/PDF extraction |
Declared but unset secrets do not stop local startup. The matching feature fails or stays disabled when invoked.
## Secret Declaration
`wrangler.jsonc` declares every Worker secret under `secrets.required`. In local development, only names declared there are loaded from `.dev.vars`, `.env`, or `process.env`.
If you add a new secret, add its name to `wrangler.jsonc`; otherwise it may never reach the Worker in local development.
## Guest Sign-In
Local development shows a **Continue as guest** button. Automation can create the same anonymous session directly:
```bash theme={null}
curl -i -c .auth.cookies -b .auth.cookies \
-H "Content-Type: application/json" \
-X POST "$APP_ORIGIN/api/auth/sign-in/anonymous" -d '{}'
```
Reuse the cookie jar for follow-up requests.
For the lower-level repo note, see [`ENVIRONMENT.md`](https://github.com/ThinkEx-OSS/thinkex/blob/main/docs/ENVIRONMENT.md).
# Local development
Source: https://docs.thinkex.app/configuration/local-development
Run ThinkEx locally from the GitHub repository.
ThinkEx is a Cloudflare Worker app managed by Vite+. The repo pins Node 24 and expects the Vite+ managed environment for local work.
## Prerequisites
* Node.js 24 (`>=24.11.0 <25`) through Vite+ managed mode
* pnpm 11
* Docker, only for the full dev profile (see [Dev server profiles](#dev-server-profiles))
* Infisical access for core team members, or a local `.dev.vars` file for contributors
If `node`, `pnpm`, or Corepack resolve to unexpected versions, run:
```bash theme={null}
vp env doctor
```
## Install
```bash theme={null}
vp install --frozen-lockfile
```
## Run with Infisical
Core team members with Infisical access can run:
```bash theme={null}
pnpm dev
```
This injects `dev:/app` secrets and starts the dev server.
## Run without Infisical
Contributors can use a local `.dev.vars` file:
```bash theme={null}
cp .dev.vars.example .dev.vars
pnpm serve:dev
```
Only two variables are required to boot the app:
```bash theme={null}
BETTER_AUTH_SECRET=local-development-secret
BETTER_AUTH_URL=http://localhost:3000
```
The auth page shows **Continue as guest** in local development, so Google OAuth credentials are not required for normal UI testing.
## Dev server profiles
`pnpm dev` and `pnpm serve:dev` run a **lite** profile by default:
* Every Cloudflare binding is emulated locally. Nothing is proxied to the real account, so a normal session incurs no Workers AI, Browser Rendering, R2, or Email charges — and no invite email is delivered to a real inbox.
* Containers are off, so Docker is never invoked and the three container images are neither built nor started.
* Miniflare's local trace store is off, which is otherwise the largest thing in `.wrangler/`.
Remote-only features are unavailable in this profile: browser rendering, PDF export, image-to-text extraction, and email invite delivery. Core workspace, document, and auth flows all run locally.
**The lite profile is not "free" — it removes the charges you did not ask for, not the ones you trigger.**
Only Cloudflare *bindings* are forced local. Three paid services are reached over plain HTTPS with an API key rather than through a binding, so no dev profile affects them:
* **AI chat, thread titles, and compaction** — Vercel AI Gateway, billed per turn whenever `AI_GATEWAY_API_KEY` is set
* **`web_search` and research tools** — Firecrawl
* **PDF text extraction** — Firecrawl
Under `pnpm dev`, Infisical supplies those keys, so sending a chat message costs money in either profile. For a session that spends nothing at all, use `pnpm serve:dev` with a `.dev.vars` that omits those keys — the AI gateway then raises a clear error instead of billing.
When you need the production-shaped environment — testing image extraction, browser rendering, real R2 behavior, or anything running in a container — opt in explicitly:
```bash theme={null}
pnpm dev:full
# or, on either command:
pnpm dev --full
pnpm serve:dev --full
```
**The full profile bills real usage** against the Cloudflare account, and sends real email. `THINKEX_DEV_PROFILE=full` is equivalent to `--full` for non-interactive callers.
## Database
Local development requires PostgreSQL. Both development commands create an isolated database from `CONDUCTOR_PORT` and `CONDUCTOR_WORKSPACE_ID` (or port 3000 outside Conductor), apply pending migrations, and pass its direct URL to Wrangler's local Hyperdrive binding automatically. Including the stable workspace ID prevents a newly created workspace from inheriting data or migration history when Conductor reuses a port:
```bash theme={null}
pnpm dev
# or, without Infisical:
pnpm serve:dev
```
Local Wrangler connects directly to PostgreSQL; it does not emulate Hyperdrive pooling or caching.
The generated connection string is per-workspace local configuration and should not be stored in
Infisical. If `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE` is already set, the
development command uses it and deliberately skips automatic creation and migrations.
## Docker
Docker is only needed for the full profile (`pnpm dev:full`), which declares Cloudflare Containers for code execution and file conversion — the first such startup may build large images. The default lite profile skips containers entirely, so Docker does not need to be running.
## Reclaim local disk
Local development artifacts accumulate per checkout and are never pruned automatically — Miniflare's trace store, locally built container images, and one PostgreSQL database per port and workspace ID ever used. To see what is reclaimable:
```bash theme={null}
pnpm dev:clean
```
That is a dry run. Add `--yes` to apply it, and optionally:
* `--databases` — also drop idle `thinkex_*` databases and their roles. Never drops this checkout's database, and never one with an open connection, so a running worktree is safe.
* `--docker-cache` — also prune Docker's build cache. This is machine-wide, so other projects lose their cached layers too.
Your local application data is never touched: `.wrangler/state/v3/do` (Durable Object storage — workspaces, documents, AI threads) and `.wrangler/state/v3/r2` (uploaded files) exist nowhere else, so no flag removes them.
## Validate Changes
```bash theme={null}
pnpm verify
```
This runs Vite+ check, test, and build tasks **through the task cache**, which fingerprints inputs and replays previous results instead of redoing work. Measured on an M-series laptop:
| Command | Nothing changed | Sources changed |
| -------------------------- | ----------------- | --------------- |
| `pnpm verify` | \~2 s | \~60 s |
| `pnpm check` + `pnpm test` | \~38 s every time | \~38 s |
So `pnpm verify` is the right habit for "is everything still OK", especially across several worktrees running the same checks on mostly-unchanged code. It is *slower* than the raw runners on a full cache miss, because it also fingerprints inputs and archives outputs — so while actively iterating, reach for the narrower commands instead:
```bash theme={null}
pnpm test --project node # ~6 s, 355 tests, skips the workerd pool entirely
pnpm check # ~5 s, format + lint + types
pnpm test # ~34 s, includes the 16 workerd test files
pnpm doctor
```
The workers test project is the slow part and is dominated by module transform and import inside `workerd`, one runtime per test file. It already runs in parallel across cores; raising `--maxWorkers` past the default makes it slower, not faster.
`pnpm doctor` runs React Doctor against changed files. Use `pnpm doctor:full` when you intentionally want a full React scan.
# Self-hosting
Source: https://docs.thinkex.app/configuration/self-hosting
Current support and requirements for running your own ThinkEx deployment.
ThinkEx is MIT licensed and can run from this repository. Today, production self-hosting means deploying into your own Cloudflare account; ThinkEx is not portable to a generic Docker host, VPS, or on-premises server.
This path is not yet turnkey or officially supported. It has not been verified from a fresh Cloudflare account, and the checked-in production configuration contains ThinkEx-owned resource identifiers that must not be reused.
## Support
| Deployment | Status |
| --------------------------------------- | ---------------------------------------------------------------- |
| Local development | Supported for contributors; core workspace flows run locally |
| Your own Cloudflare account | Possible with manual provisioning; not yet verified or supported |
| Docker, VPS, Kubernetes, or on-premises | Not supported |
For local use, follow [Local development](/configuration/local-development). The lite profile emulates Cloudflare bindings but omits remote-only features such as browser rendering, PDF export, image extraction, and email delivery.
## Production requirements
A production deployment needs:
* A Cloudflare account with Workers, Durable Objects, R2, Workflows, Containers, Images, Browser Rendering, Worker Loaders, Hyperdrive, and email sending available.
* A PostgreSQL database reachable through a cache-disabled Hyperdrive configuration.
* A custom domain, Better Auth secret, and Google OAuth credentials. Guest sign-in is development-only.
* R2 API credentials and a separate upload-token secret for direct file uploads.
* Provider keys for the features you enable: AI Gateway for AI chat and Firecrawl for web tools and document extraction. Analytics integrations are optional.
## Account-specific setup
Before deploying, replace the ThinkEx-owned values in `wrangler.jsonc`:
1. Worker name and custom domain route.
2. R2 bucket name in both the binding and `R2_BUCKET_NAME`.
3. Hyperdrive configuration ID.
4. Both Cloudflare Container image digests. Build the checked-in Dockerfiles into your own account; the pinned production images belong to the ThinkEx account.
Also update the allowed origin in `config/r2/cors.production.json`, configure the bucket CORS and abandoned-upload lifecycle rules, and set the production secrets described in [Environment](/configuration/environment).
The normal release order is:
1. Apply the Postgres migrations with `DATABASE_URL` set to a direct administrative connection.
2. Build with `pnpm build:production`.
3. Deploy with `CLOUDFLARE_ENV=production pnpm deploy:worker`.
See [Deployments](/configuration/deployments) for the existing build, migration, container, and R2 commands. Do not call a deployment complete until sign-in, workspace creation, file upload, document editing, realtime collaboration, AI chat, and file processing have been tested against the new account.
# Collaboration
Source: https://docs.thinkex.app/guides/collaboration
Share a workspace with members and invite links.
ThinkEx workspaces can be shared with other members. Membership controls both content mutation and invite permissions.
## Invite People
Open the workspace share dialog.
Pick the role for the invite. Members can only invite at their own role or below.
Email invites are single-use. Invite links are role-specific and expire after seven days.
Owners and eligible admins can update member roles or remove members from the share dialog.
## Role Rules
| Rule | Behavior |
| ----------------------- | -------------------------------------------------------- |
| Invite down | A member can only grant their role or lower |
| No owner grants | Ownership is not granted through normal invites |
| No accidental downgrade | Accepting an invite never lowers an existing member role |
| Viewer mode | Viewers get read-only workspace access |
Email invites require the Cloudflare Email binding and sender configuration. Local development can still exercise most workspace flows without email delivery.
# Import files
Source: https://docs.thinkex.app/guides/import-files
Add PDFs, office documents, images, Markdown, code, and text to a workspace.
Use file import when you want source material to become part of a workspace.
## Add Files
Go to the workspace where the source material belongs.
Drag files into the workspace or use the workspace upload controls.
The upload intake accepts supported files and rejects unsupported files with a specific message.
Larger PDFs, office files, and images may need conversion, preview generation, or text extraction before every AI feature is available.
## Supported Formats
| Kind | Formats | Result |
| --------------- | ------------------------------------ | -------------------------------------------------- |
| PDF | `.pdf` | File item with PDF viewer, preview, and extraction |
| Word | `.docx` | Converted to PDF file item |
| PowerPoint | `.pptx` | Converted to PDF file item |
| Image | `.png`, `.jpg`, `.jpeg`, `.webp` | Image file item |
| iPhone image | `.heic`, `.heif` | Converted to JPEG image item |
| Text-like files | CSV, TSV, Markdown, code, plain text | Document item |
## Limits
| Limit | Value |
| ------------------- | ------ |
| Files per selection | 50 |
| Bytes per selection | 100 MB |
| Upload concurrency | 3 |
For AI-heavy work, upload only the sources you need for the current workspace. Smaller, well-named workspaces are easier to navigate and easier to ask about.
# ThinkEx MCP Server
Source: https://docs.thinkex.app/guides/mcp
Connect compatible AI clients to ThinkEx workspaces with MCP and OAuth.
ThinkEx provides a remote [Model Context Protocol](https://modelcontextprotocol.io/) server for working with your workspace content from compatible AI clients.
Use `https://thinkex.app/mcp` as the server URL. ThinkEx uses browser-based
OAuth, so you do not need to create an API key, client ID, or client secret.
## Connect a Client
Your client must support remote Streamable HTTP MCP servers with OAuth.
In Claude or Claude Desktop, open **Customize → Connectors**. Team and Enterprise owners add custom connectors from **Organization settings → Connectors**.
Choose **Add custom connector**, enter `ThinkEx` as the name, and use `https://thinkex.app/mcp` as the remote MCP server URL.
Select **Connect**, sign in to ThinkEx, review the requested permissions, and choose **Allow**.
Open the connectors menu from the chat composer and enable ThinkEx for the conversation.
See [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for plan and organization controls.
Add ThinkEx to your global `~/.cursor/mcp.json` or a project's `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"thinkex": {
"url": "https://thinkex.app/mcp"
}
}
}
```
Start or refresh the server from Cursor's MCP settings, then complete the browser sign-in and consent flow. See [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol) for configuration locations and controls.
Run **MCP: Add Server** from the Command Palette and choose an HTTP server, or add ThinkEx to your user or workspace `mcp.json`:
```json theme={null}
{
"servers": {
"thinkex": {
"type": "http",
"url": "https://thinkex.app/mcp"
}
}
}
```
Start the server and use the **Auth** action above its configuration to complete sign-in. See [VS Code's MCP server guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for user, workspace, and organization configuration.
## Permissions
The consent screen requests two permissions:
| Permission | Allows |
| ------------------------ | -------------------------------------------------- |
| View workspaces | List your workspaces and read their contents |
| Manage workspace content | Create, edit, move, link, rename, and delete items |
OAuth permission does not override your workspace role. ThinkEx checks your current membership on every operation:
| Workspace role | MCP access |
| ----------------------- | --------------------------------- |
| Owner, admin, or editor | Read and modify workspace content |
| Viewer | Read workspace content only |
| No membership | No access |
If your role changes or you lose access to a workspace, the change applies to subsequent MCP operations.
## How Workspace Selection Works
The client first asks ThinkEx for the workspaces available to your account. Each result includes the workspace name, stable ID, and your role. The client uses the name to understand your request and passes the exact ID back to ThinkEx for later operations.
Within a selected workspace, items use readable absolute paths such as `/Research/Notes`. Workspace names are not used as identifiers, so duplicate or renamed workspaces remain unambiguous.
## Available Actions
Connected clients can:
* List available workspaces and membership roles.
* Browse folders and workspace items.
* Read documents and extracted file content.
* Create folders and documents.
* Edit documents and item relationships.
* Rename, move, link, and delete workspace items.
ThinkEx exposes these capabilities through a compact code-mode interface so clients do not need to load every operation schema into the conversation at once.
Connected clients can change or delete content when your workspace role allows
it. Review permission prompts and consequential tool calls in your AI client.
## Troubleshooting
| Problem | What to check |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| A workspace is missing | Confirm that the same ThinkEx account is still a member and that the workspace is not archived |
| Reads work but writes fail | Your workspace role may be viewer, or the client may not have write permission |
| The client shows no ThinkEx actions | Confirm it supports remote Streamable HTTP MCP with OAuth, then restart or reconnect the server |
| Authorization keeps restarting | Remove the connection from the client, add `https://thinkex.app/mcp` again, and complete consent in one browser session |
# ThinkEx
Source: https://docs.thinkex.app/index
A workspace for source-heavy study, research, and creation.
ThinkEx is a workspace for source-heavy work. Keep PDFs, documents, images, folders, and AI chat in the same place, then choose exactly what the AI should use.
![ThinkEx workspace with documents, folders, and AI assistant]()
Create a workspace, add sources, and ask AI about selected context.
Learn how ThinkEx organizes source material and collaboration.
Understand documents, files, and folders.
Run the Cloudflare Worker app locally without production secrets.
## When a Chat Thread Is Not Enough
ThinkEx is not a file dump behind a chat box. The sources stay visible and usable while you work:
* Open PDFs, documents, images, and folders in a workspace.
* Arrange sources side by side while you read, compare, or write.
* Ask AI about the exact items or selected passages you choose.
* Share workspaces with other members when the work is collaborative.
## How It Is Different
| Compared with | What they are good at | Where ThinkEx differs |
| ---------------------------- | ---------------------------------------- | --------------------------------------------------------- |
| ChatGPT, Claude, Gemini | Fast AI conversations | Chat is part of the workspace, next to sources and docs |
| Gemini Notebook (NotebookLM) | Asking questions over uploaded sources | Sources stay open, arrangeable, editable, and shareable |
| Obsidian | Markdown files and local knowledge bases | PDFs, images, docs, AI chat, and sharing are first-class |
| Google Drive, Dropbox | Storing and sharing files | Files become source material with docs and AI beside them |
## Built On Cloudflare
ThinkEx is a full-stack TypeScript app hosted on Cloudflare Workers. It uses PlanetScale Postgres through Hyperdrive for relational and canonical workspace state; Durable Objects for realtime workspace, document, AI, sandbox, and conversion coordination; R2 for binary workspace file storage; Workflows for extraction; Containers for code execution and file conversion; Workers AI, Images, Browser Run, and Email for product features.
For repository-level setup details, see the [README](https://github.com/ThinkEx-OSS/thinkex) and [local development](/configuration/local-development) guide.
# Contributing
Source: https://docs.thinkex.app/project/contributing
How to work on ThinkEx safely.
ThinkEx is a production application, not a demo or template. Contributions should prioritize reliability, maintainability, and clear user value.
## Local Setup
```bash theme={null}
git clone https://github.com/ThinkEx-OSS/thinkex.git
cd thinkex/web
vp install --frozen-lockfile
```
Core team members with Infisical access can run:
```bash theme={null}
pnpm dev
```
Contributors without Infisical should copy `.dev.vars.example` to `.dev.vars`, set `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`, and run:
```bash theme={null}
pnpm serve:dev
```
The app runs at `http://localhost:3000`.
## Pull Requests
* Keep changes focused.
* Explain what changed and why.
* Include testing notes.
* Do not include generated build output.
* Do not run deploy, remote migration, legacy-data, or secret-management commands unless a maintainer asks for them.
## Useful Commands
```bash theme={null}
pnpm dev
pnpm serve:dev
pnpm check
pnpm test
pnpm build
pnpm doctor
pnpm doctor:full
pnpm verify
```
Use `pnpm verify` before opening a pull request when possible.
Use `pnpm doctor` for a React Doctor scan of changed files; pull requests also run the React Doctor workflow for inline React diagnostics.
## Help
Join the [ThinkEx Discord](https://discord.gg/dtPnzkqCcG) for setup help, contribution scope, and local development questions.
# Supporters
Source: https://docs.thinkex.app/project/supporters
Programs and platforms supporting ThinkEx.
ThinkEx is supported by programs and platforms that provide credits, tooling, infrastructure, and product support.
# Quickstart
Source: https://docs.thinkex.app/quickstart
Create your first ThinkEx workspace.
The fastest way to use ThinkEx is [thinkex.app](https://thinkex.app). This guide describes the product flow, not local development.
## Create a Workspace
Open [thinkex.app](https://thinkex.app) and sign in. Local development builds also show **Continue as guest**, so contributors can test the app without Google OAuth.
From the home page, create a workspace. A workspace is the container for your items, tabs, chat threads, members, and history.
Drag supported files into the workspace or create documents and folders from the workspace controls. ThinkEx currently accepts PDFs, Word documents, PowerPoint presentations, images, CSV, TSV, Markdown, code, and text files.
Open items in tabs, keep sources side by side, and organize related items into folders.
Select the item or passage you want the AI to use, then ask from the chat panel or contextual ask controls. The point is explicit context, not hidden retrieval.
## Next Steps
See which item types ThinkEx supports.
Learn how workspace-aware AI tools work.
Review upload limits and conversion behavior.
Run the app from this GitHub repo.