NeuroDock (hosted)

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- /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/):

   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.

1. 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.