Foundation delivery and rollout

Inputs and scope

This plan covers WorkOS authentication and the two tools, hello_read and hello_write, within the Product scope. Adopt the proposed ADR-024 and approve the design before implementing work that depends on it.

Delivery sequence

1. Check WorkOS and client compatibility

Choose the client/version and test environment, obtain approval for the WorkOS configuration, and agree how much time to spend on the investigation. Check that the client can register, sign in and renew access for the intended MCP address and organization. Verify that Auth Boundary can obtain the required identity and current WorkOS permissions.

Choose the library and protocol revision together from the library comparison and client compatibility findings. Neither is settled by the reference server's use of Chimp. Test the intended client's actual protocol mode before settling on a revision. A client or library version number is not an MCP protocol version. Record the client and library versions, active client mode, revision used in successful requests and results for unsupported or missing version metadata. Follow the lifecycle and transport rules of each revision claimed as supported; see Program design: protocol versions.

Use the authentication contracts to check registration, metadata, PKCE, token audience, identity and consent. Also try cancelled sign-in and recovery when automatic renewal fails. Record whether the client retries the original request or the user needs to send it again. Keep secrets out of the results.

Before moving on: record what works, any provider or client limitations, and whether to proceed or revise the design. Saving a connection is not proof that authentication works, and successful sign-in is not proof of tool access. This investigation informs AC-1, AC-3 and AC-5.

2. Build the complete foundation

After the compatibility check and implementation approval, build authentication, both tools and their access controls together. Prepare the shared permission definitions, configuration and approved user grants.

Before making MCP available: pass the server and provider tests for AC-1, AC-2, AC-3, AC-4, AC-5 and AC-6. These include tenant isolation, permission checks, expiry, provider failures and unchanged browser authentication. Do not postpone security controls to the next step. The release must be safe to deploy with MCP off for every tenant.

3. Verify the deployed release

With deployment and activation approved, run the manual test plan and operational checks against the chosen release. Check setup, permissions, renewal, recovery and switching MCP off and on. Inspect logs and Sentry while testing.

Before acceptance: resolve blocking findings and record the release, environment, client/version, results and the acceptance decision. Record any remaining work before wider use. Passing automated tests or merging the code does not establish acceptance or availability.

Planned PR set

The proposed split is three PRs:

1. Specification and ADR: review the scope, design and delivery plan, and adopt the required decision before dependent implementation.
2. Implementation: deliver the complete foundation from step 2, with tests and setup guidance. One PR can cover both tools; individual stories do not need separate PRs. Merging it does not deploy or accept the feature.
3. Operation and results: add verified operating instructions and the results from step 3, including the acceptance decision. Review any code fixes separately and rerun affected checks before resuming activation.

Start each PR from current main with its prerequisites merged. If approved work needs to start on an unmerged dependency, coordinate the branches and rerun checks after rebasing. Explain any change to this proposed split.

If the compatibility check needs a test harness, keep it separate from production routes and business data. Keep useful results and agree what happens to the harness afterward; it must not become a production authentication bypass. Split out a prerequisite refactor only when shared-code risk justifies a separate review.

Dependencies and safe intermediate states

Prepare the environment

Keep MCP off for every tenant after deployment. Configure the MCP address, issuer and organization, both permission definitions, approved user grants and the WorkOS flag entitlement-remote-mcp-org. Set finite request and provider time limits, plus size, rate and concurrency limits. If access is cached, set its maximum age too. Missing required configuration must deny access. Permission setup checks must not grant access or delete unrelated definitions.

Resolve and test expiry during an ongoing request before activation. A delay in applying a changed WorkOS flag must not allow a request to outlive its authorization.

Enable a controlled test

An authorized operator enables the flag only for the chosen tenant and environment. The flag alone grants no user permissions. Record the MCP address, operational owner and maximum delay before changed access takes effect alongside the release details. Immediately check allowed and denied requests, plus existing browser authentication.

Stop access or roll back

Turn off the organization's WorkOS flag and check that protected requests stop within the agreed time limit. An unavailable WorkOS lookup must not extend expired access. OAuth metadata, bearer authentication and browser access remain usable.

For an emergency, withdraw the MCP route or roll back the release. Account separately for tokens already issued and requests already running; switching off the flag does not revoke tokens immediately. The two tools change no business data, so there is no business-data rollback.

Expand availability

Define who should receive access and verify the intended release before expanding use. Internal availability and final acceptance remain separate decisions. No fixed observation period is required; add one only for a stated reason, with a workload, duration, measurable criteria and a decision owner.