Authentication and access architecture

Architecture decisions

The ADRs record the decisions and their reasons. This page explains how the proposed MCP design fits into Platform.

Prerequisite reading and WorkOS context

These WorkOS guides explain how clients connect and what Platform needs to check:

• MCP protocol specification: protocol, transport and authorization requirements. See Program design: protocol versions for the compatibility assessment and open version choice. This link does not select the delivery's protocol revision.
• AuthKit for MCP: how an MCP client connects through WorkOS.
• OAuth applications and consent: sign-in, organization selection and approving a connection and reusing an existing approval.
• Connect access-token claims: what the token contains and which user permissions Platform must look up separately.

The responsibilities are:

• WorkOS Connect provides the OAuth endpoints for MCP, hosts sign-in and connection approval, and issues and renews access tokens.
• Platform provides the MCP service. It checks the tenant, whether MCP is enabled, and which tools the user's permissions allow.

The connection sequence shows how WorkOS and Platform work together. Program design describes the implementation and tests. Delivery plan describes the order of the work.

Configure WorkOS Connect

Before connecting a client:

• Enable client identification through CIMD in Connect. Enable DCR too if the supported client needs it.
• Register the HTTPS MCP endpoint as a Resource Indicator in WorkOS Connect. The client's resource parameter and the server metadata's resource must identify the same endpoint.
• Auth Boundary must verify the token, including checking that its audience (aud) matches that concrete endpoint.

WorkOS also supports wildcard Resource Indicators. A pattern can contain one wildcard: in the leftmost subdomain label, or as the entire final path segment. It cannot be the default Resource Indicator. The issued token's audience is always the concrete requested URL, never the wildcard pattern. This does not relax our tenant, environment or audience checks.

MCP server reference implementation

The MCP server reference implementation is a small HTTP server in a single file. It lets us test how a real client handles successful replies, HTTP failures and tool errors.

It uses Chimp for MCP, with Tapir and Netty, which Platform already uses. Chimp is the only new library in this combination. This is the reference server's stack. The production library remains an open choice in Program design.

Use the test results to check whether the client behaves as described here and in the mockups.

The reference server does not connect to WorkOS or use Platform data. It simulates replies without signing anyone in or checking their actual permissions. Its 401 response cannot test OAuth sign-in. The recorded results come from a local client. Cloud-client behavior and real OAuth recovery still need separate testing.

Fit and ownership

MCP requests use an access token, also called a bearer token. Auth Boundary handles it separately from browser authentication, while reusing tenant resolution and internal credential mechanisms. MCP does not accept browser sessions or caller-supplied identity headers as proof of identity. Auth Boundary currently lives in modules/web; that module location does not move authentication into tool handlers.

Authentication and tenant boundary

Match the token to the connection

The MCP adapter uses the existing tenant resolver and deployment configuration to identify the connection. Auth Boundary checks the token against that connection before passing the request into Platform. The exact resource, audience and organization rules are defined in ADR-024: tenant-bound resources.

Verify identity at the entry point

The MCP bearer adapter belongs in Auth Boundary, alongside the existing browser authentication path. It verifies the external token and preserves the verified human, organization, client and consent identity. ADR-024: external authentication defines the token checks and protection against forged internal identity. Program design maps those requirements to interfaces and types.

Look up access in WorkOS

Use the WorkOS feature flag Remote MCP access for organizations, with slug entitlement-remote-mcp-org. It controls MCP availability for the organization, separately from the user's read and write permissions.

After verifying the token, Auth Boundary looks up the organization's MCP flag, the user's active membership and effective permissions.

These checks run on the server. Do not assume the Connect token contains permissions, groups or feature flags. Connect token guidance documents the permission lookup; organization feature flags provide the MCP-flag lookup. The complete access-resolution rules are in ADR-024: external authentication.

Pass verified identity into Platform

Auth Boundary issues an internal MCP credential after authentication and access resolution succeed. Platform verifies it before building request context; tool handlers do not verify WorkOS tokens or query WorkOS. Reuse the existing internal credential machinery with the channel separation and expiry rules in ADR-024: external authentication.

Request and connection sequence

The sequence diagram in ADR-024 shows the OAuth exchanges, server-side checks and token renewal.

Authorization and authority lifetime

Check every protected request

One shared policy protects protocol lifecycle requests, discovery and invocation. MCP must be enabled for the tenant, and the user needs mcp:read; hello_write also requires mcp:write. ADR-024: user permissions defines the access rules. Program design applies them through the shared access policy and explicit tool definitions.

Limit reuse of access lookups

Auth Boundary may cache the WorkOS access result as a short-lived access snapshot. This avoids a provider call on every request, but reuse must not extend the original deadline. ADR-024: freshness and revocation defines cache binding, expiry and failure rules. Program design describes the lookup and cache contract.

Apply access changes within a known delay

Caching means permission changes and tenant disablement may take time to reach existing connections. Choose and verify that maximum delay before activation, under ADR-024's freshness rules. Keep the route and public authentication metadata available when the tenant is disabled. The failure contract maps authentication, access and provider failures to distinct replies and recovery steps.

Keep renewal and consent withdrawal separate

The client renews tokens directly with WorkOS. Auth Boundary verifies the new token and resolves access again. Permission freshness and consent withdrawal are different controls; a fresh lookup does not prove immediate revocation. Their lifetime limits are defined in ADR-024: freshness and revocation. Verify the actual renewal and withdrawal behavior in the chosen WorkOS environment and client before activation.

State, effects and attribution

The tools have no inventory, repository, projection or event-journal dependency. They need no business-data storage or migration.

Logs and monitoring record the verified user, client, consent ID, resource, channel, tenant and correlation ID where known. If a request is denied before identity is established, record it as unknown. Never include secrets or business data.

Reuse Platform's existing Sentry integration for MCP errors and HTTP request tracing. Add spans around WorkOS access lookups so operators can distinguish a slow or failed lookup from other request failures. Follow the existing sampling and payload allowlists; do not send tokens, credentials or business data to Sentry.

These records show that the client acted with the user's access. They do not prove that the user approved each action. This delivery adds no confirmation step for individual tool calls.

Alternatives and consequences

The reasons for this direction and the rejected alternatives are recorded in ADR-024: rationale and alternatives.

For this implementation, reusing Auth Boundary keeps external authentication out of tool handlers. WorkOS lookups add latency; an optional cache reduces calls but delays access changes. The two fixed-message tools need no shared business-operation layer.

Compatibility, activation and rollback

MCP starts turned off for every tenant. Installing a new release must not turn it on.

Before turning it on, configure the MCP address, tenant routing and WorkOS organization. Create the required permissions and assign them to the intended users. Then enable the MCP feature flag for the selected organization in WorkOS.

To turn MCP off for a tenant:

1. Turn off the organization's MCP feature flag in WorkOS.
2. Check that MCP requests are denied, including requests from clients that are already connected. The server may briefly reuse an earlier permission check. Access must stop within the configured time limit for reusing those checks.
3. Check that browser sign-in and the public information clients use to find the OAuth server still work.

Turning off the flag leaves the MCP endpoint in place. If an incident requires taking the endpoint down as well, remove its routing or configuration, or roll back the release. That is a separate deployment action.

The two tools change no business data, so rolling back this release requires no business-data recovery.

Removing a connection from an MCP client does not necessarily revoke its WorkOS authorization or invalidate its tokens. Document separately how to withdraw consent and how long issued tokens can remain usable.