For Stakeholders

Where this actually stands

This is PR #425, feat/claude-mcp, opened by its own author as "Draft — not for review or merge yet." Its stated purpose is narrower than the feature itself: to exercise CI and a real HTTPS sandbox domain, because cookies, CSP, and cross-origin redirects behave differently on a real hostname than on a developer's laptop, and this branch had already hit real bugs from that gap before this PR was opened. Treat this as infrastructure validation for a feature still in progress, not a release candidate.

One specific gap worth flagging to whoever owns the release decision: the PR description states the sandbox "exercises the OAuth server over real HTTPS." We verified directly against the live sandbox that this is not currently true — the sandbox is missing the environment variables (OAUTH_ISSUER, OAUTH_MCP_RESOURCE, OAUTH_CLINIC_WEB_LOGIN_URL) that turn the OAuth routes on at all, so today they simply aren't mounted there. This doesn't mean the code is untested — it has its own substantial CI suite — but it does mean the specific "real HTTPS, real cookies" validation this PR was opened to get has not actually happened on this sandbox yet.

Why this matters strategically

Clinics currently get insight out of Dentolize by looking at dashboards or exporting reports. This is a bet that a conversational interface — "what's running low, what did we spend with suppliers" — reduces the friction of actually using the data a clinic already has. Phase 1 deliberately picks the lowest-risk starting surface (inventory, read-only) rather than anything patient-facing or financial, which limits both the immediate value and the immediate exposure while the approach gets proven out.

Risk profile

What's been engineered against:

• Cross-tenant data leakage — the single most serious failure mode

available in a shared-database, multi-tenant medical system. This is defended at the database layer (row-level security, a role with SELECT-only access) rather than relying solely on application code remembering to filter correctly, and it's backed by an automated two-clinic leak test.

• Write access — architecturally impossible in this phase; the database

login the feature uses cannot write, full stop.

• Credential/token abuse — rate limiting, connection pool caps, query

timeouts, row and date-range caps, and instant revocation. Design document is explicit that the worst case of a stolen token is unwanted read load on one clinic — never write access, never a second clinic.

What has not yet been engineered:

• No self-service revocation. A doctor or owner cannot yet see or

disconnect their own Claude connection from within Dentolize. This is explicitly listed as scoped-out future work in the design document, not an oversight — but it is a real gap if this ships broadly before that screen exists, since "how do I turn this off" is a predictable first question from a security-conscious clinic owner.

• The MCP server is not part of the deployed stack anywhere, including

the sandbox — it exists as a package and a CI job, not a running service. Actually deploying it (adding it to docker-compose.yml / ecosystem.config.js) is explicitly called out as "the next commit," not part of this one.

Testing depth, as evidence this is being taken seriously

Per the PR's own CI workflow: 249 tests for the MCP server (including a dedicated two-clinic leak suite, and "parity" tests that check every tool's answer against the API's own equivalent query), 259 tests for the new OAuth endpoints, and mutation testing over the database-independent modules with a 75% minimum score gate (currently at 80.29%). See For Quality for what that actually covers and where the edges still are.

What to watch for before this is release-ready

1. Confirm the sandbox gap above is closed before treating "tested on a real

domain" as done.

1. Confirm a revocation/management UI is planned before this reaches clinics

broadly — right now that's an internal-only capability.

1. Confirm the deployment step (adding claude-mcp to the actual running

stack) has landed and been validated, since this PR explicitly does not include it.