Skip to main content
Client MCP access lets an AI client act only for the authenticated client who approved the connection. It uses the same remote MCP endpoint as company MCP, but the grant has subjectType: "client" and a fixed subjectClientId. Client MCP is available only when the company MCP integration feature is enabled, the client is connected to the active company, client AI access is enabled for that client-company relationship, and the company’s client MCP policy allows client connections plus the requested client_ai_* modules.
The client-company entitlement is stored with the canonical clientAiAccessEnabled, clientAiAccessStartDate, and clientAiAccessEndDate fields. Existing foodRecognitionEnabled, foodRecognitionStartDate, and foodRecognitionEndDate values remain supported as legacy fallback fields and are still written during the transition.

​
Client Portal Flow

Client MCP consent belongs in the company-branded client portal, not in the coach dashboard. The client stays in the active company context, and the backend resolves the company and client from the authenticated client session. The authorize endpoint hands the consent page only an opaque single-use transaction id (valid for 10 minutes); the OAuth parameters never travel through the consent URL. The consent page reads the pending request through GET /app/v1/client/mcp/oauth/transactions/:transactionId, approves it with POST /app/v1/client/mcp/oauth/approve (body: transactionId plus the consent choices), or declines it with POST /app/v1/client/mcp/oauth/transactions/:transactionId/deny. Approval or denial consumes the transaction exactly once and returns the redirect URL for the AI client, built from the stored redirect URI and state; an expired or consumed transaction requires restarting the connection from the AI client. The approval gate is strict:
  1. If company MCP access is disabled, approval fails with COMPANY_MCP_FEATURE_DISABLED.
  2. If the client is not connected to the active company, approval fails with COMPANY_MCP_CLIENT_COMPANY_CONNECTION_REQUIRED.
  3. If client AI access is disabled for that company relationship, approval fails with COMPANY_MCP_CLIENT_AI_DISABLED.
  4. If the company’s client MCP policy is disabled or has no allowed modules, approval fails with COMPANY_MCP_CLIENT_MCP_DISABLED.
  5. Only after those checks pass can the client approve explicit client_ai_* modules and optional write tools that the company policy allows.
If the product exposes a “request access” action when client AI access is disabled, that request should notify the assigned coach and company admins. It must not create an MCP grant or issue OAuth tokens. The company must first enable client AI access for that client-company relationship; the client can then retry the OAuth consent flow.

​
How It Differs

Client grants cannot request coach/company modules such as clients, client_notes, bookings, or invoices. The backend accepts only the client AI module registry listed below.

​
Client AI Modules

Client AI modules follow the same sensitivity model as company MCP:
  • health modules require explicit health data consent from the client.
  • private_communication modules require explicit private communication consent from the client.
  • operational modules do not require an extra consent flag beyond the OAuth approval.

​
Runtime Filtering

At runtime, tools/list and tools/call are filtered by:
  • subjectType
  • subjectClientId
  • allowedModules
  • allowedWriteTools
  • healthDataConsent
  • privateCommunicationConsent
  • company MCP integration feature
  • client AI access for the active company relationship
  • company client MCP policy
  • grant status and expiry
For client grants, the backend filters the tool registry to client_ai_* modules and then enforces that every tool call resolves to the authenticated client.