neurodock-remote

The combined remote MCP server for NeuroDock (ADR 0008 / ADR 0009, Phase 2).

It composes the three stateless NeuroDock servers into a single Streamable HTTP endpoint and exposes only the remote-safe tools:

Opt-in storage surface (ADR 0010 Phases C/D)

The four cognitive-graph tools (recall_entity, record_fact, recall_decisions, weekly_rollup) are also exposed, but gated: they require a signed-in account that has explicitly enabled storage. Two modes coexist; a user is in exactly one at a time:

The mode is selected per user from their recorded storage preference; a single combined resolver routes each cognitive-graph call to the hosted or BYOS backing. The privacy boundary is unchanged from Phase D: an anonymous / no-token caller gets STORAGE_NOT_AVAILABLE and nothing is stored, read, or provisioned; a signed-in but not-enabled caller gets STORAGE_NOT_CONNECTED.

Hosted requires a provisioned Turso org/group/token. Set NEURODOCK_TURSO_PLATFORM_TOKEN + NEURODOCK_TURSO_ORG (+ optional NEURODOCK_TURSO_GROUP, default default, which must already exist in the org). Without them enable_hosted_storage is refused and only BYOS is offered.

Encryption-key custody (honest limitation). Both the BYOS auth token and the hosted Turso DB token are encrypted at rest with a single operator-wide NEURODOCK_STATE_MASTER_KEY. That means NeuroDock can technically decrypt a stored token. This is the documented ADR 0010 open question; per-user / envelope keys (so the operator cannot unilaterally read a user's DB token) are a tracked follow-up. The on-disk format is unchanged either way, so a future scheme can re-wrap without a data migration.

What is deliberately NOT here

Chronometric session state, the user profile (neurotype data), and task-fractionator's next_one (reads the local graph) are never mounted. They hold local state and stay strictly on the local stdio install. The boundary is enforced in code and pinned by tests against REMOTE_TOOL_NAMES.

This is a deploy artifact, not a published package — it is not uploaded to PyPI (the local install path via @neurodock/cli is unchanged). Local-only tools remain available exactly as before through the stdio servers.

Skills delivery (hosted/remote users)

The remote server exposes tools, not skills. Skills are markdown the client reads locally, so the remote endpoint never delivers them. Hosted/remote users get the per-neurotype skills the same way local users do: install the Claude Code marketplace plugin (which bundles them) or run neurodock install-skills from @neurodock/cli, which copies each skill into ~/.claude/skills/neurodock-<name>/SKILL.md for Claude Code / Claude Desktop. See packages/skills/README.md for the delivery paths.

Run locally

# from the repo root
uv run --package neurodock-remote neurodock-remote
# serves http://127.0.0.1:8000/mcp  (+ /health)

Inspect it with the MCP Inspector pointed at http://127.0.0.1:8000/mcp.

Configuration

⚠️ Auth is required before public exposure. With NEURODOCK_AUTH_PROVIDER unset the server runs unauthenticated and logs a loud warning — that mode is for localhost/integration testing only (ADR 0009 §3). The identity provider is a configuration choice, not a code change; FastMCP ships first-class Clerk, WorkOS AuthKit, and Auth0 providers plus the generic JWT verifier wired here.

Container (any host)

# build from the repo root (the Dockerfile uses root-relative COPY paths)
docker build -f packages/remote/Dockerfile -t neurodock-remote .
docker run --rm -p 8000:8000 \
  -e NEURODOCK_AUTH_PROVIDER=clerk \
  -e NEURODOCK_CLERK_DOMAIN=your-app.clerk.accounts.dev \
  -e NEURODOCK_CLERK_CLIENT_ID=xxxx \
  -e NEURODOCK_CLERK_CLIENT_SECRET=yyyy \
  -e NEURODOCK_PUBLIC_URL=https://mcp.neurodock.org \
  neurodock-remote

Deploy to Cloudflare Containers

The chosen host (ADR 0009). The Python container runs on Cloudflare Containers, fronted by a thin Worker (worker/index.ts) that owns the mcp.neurodock.org custom domain. Config: wrangler.jsonc.

Requires a Workers Paid plan — Containers are not on the free tier. The Worker + container are deploy tooling only; this directory is intentionally not a pnpm-workspace member, so install/deploy happen here directly.

1. Create a Clerk OAuth application and note the instance domain + client ID/secret.

2. Fill vars in wrangler.jsonc (NEURODOCK_CLERK_DOMAIN, NEURODOCK_CLERK_CLIENT_ID) — these are non-secret.

3. From this directory (packages/remote/):

   bash

   npm install
   npx wrangler secret put NEURODOCK_CLERK_CLIENT_SECRET   # paste the secret
   # Optional — enable the opt-in memory tools (ADR 0010 C/D). Without the next
   # two the tools stay visible but un-backed (sign-in/enable refusal):
   npx wrangler secret put NEURODOCK_CLERK_SECRET_KEY      # Clerk Backend API key
   npx wrangler secret put NEURODOCK_STATE_MASTER_KEY      # token-encryption master key
   # Optional — enable NeuroDock-hosted storage (ADR 0010 C). Also set
   # NEURODOCK_TURSO_ORG (and NEURODOCK_TURSO_GROUP) in wrangler.jsonc `vars`.
   # Without the token + org, enable_hosted_storage is refused; BYOS still works:
   npx wrangler secret put NEURODOCK_TURSO_PLATFORM_TOKEN  # Turso Platform API token
   npx wrangler deploy                                     # builds ../Dockerfile, pushes, deploys
   

   wrangler deploy builds the image (context ../../ = repo root), provisions the mcp.neurodock.org DNS + TLS automatically (the custom_domain route), and starts the container behind the Worker.

4. Verify: https://mcp.neurodock.org/health → 200, then add https://mcp.neurodock.org/mcp as a custom connector in Claude and complete the Clerk OAuth round-trip.

See ADR 0009 for the transport, scope, auth, and hosting decisions.

Status: this Cloudflare deploy config is a verified-by-docs scaffold; it has not yet been run through wrangler deploy. Treat the first deploy as the validation step.