Client AI Access - FITsociety Developer APIs

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.

https://mcp.fitsociety.io/mcp/v1

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 approval gate is strict:

If the company mcp feature flag is disabled, approval fails with COMPANY_MCP_FEATURE_DISABLED.
If the client is not connected to the active company, approval fails with COMPANY_MCP_CLIENT_COMPANY_CONNECTION_REQUIRED.
If client AI access is disabled for that company relationship, approval fails with COMPANY_MCP_CLIENT_AI_DISABLED.
If the company’s client MCP policy is disabled or has no allowed modules, approval fails with COMPANY_MCP_CLIENT_MCP_DISABLED.
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

Area	Company/coach grant	Client AI grant
Approver	Manager or Admin coach	The authenticated client
Approval route	`POST /app/v1/company/mcp/oauth/approve`	`POST /app/v1/client/mcp/oauth/approve`
Subject	Company-scoped coach/admin access	One client in the active company
Feature gate	Company MCP integration feature	Company MCP integration feature plus client AI access and company client MCP policy
Static API keys	Supported	Not supported
Allowed modules	Company/coach modules	Only explicit `client_ai_*` modules allowed by company policy
Revocation	Coach/company MCP settings	`POST /app/v1/client/mcp/grants/:grantId/revoke`

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

Module Key	Sensitivity	Tools
`client_ai_account`	`operational`	`client_ai_get_my_subscription`, `client_ai_list_my_invoices`, `client_ai_get_my_credits`
`client_ai_bookings`	`operational`	`client_ai_list_my_events`, `client_ai_list_my_bookings`, `client_ai_book_my_event`, `client_ai_cancel_my_booking`
`client_ai_measurements`	`health`	`client_ai_get_my_measurements`, `client_ai_list_my_measurement_types`, `client_ai_log_my_measurement`
`client_ai_checkups`	`health`	`client_ai_list_my_checkups`, `client_ai_get_my_checkup`, `client_ai_submit_my_checkup`
`client_ai_habits`	`health`	`client_ai_list_my_habits`, `client_ai_get_my_habit_entries`, `client_ai_check_in_my_habit`
`client_ai_goals`	`health`	`client_ai_get_my_goals`, `client_ai_update_my_goals`
`client_ai_documents`	`private_communication`	`client_ai_list_my_documents`, `client_ai_get_my_document_download_link`
`client_ai_messages`	`private_communication`	`client_ai_list_my_chats`, `client_ai_get_my_messages`, `client_ai_send_message_to_my_coach`
`client_ai_nutrition`	`health`	`client_ai_get_my_nutrition_day`, `client_ai_list_my_nutrition_days`, `client_ai_search_food_products`, `client_ai_search_recipes`, `client_ai_log_my_food`
`client_ai_workout_v2`	`health`	Assigned plans/days, visible exercise detail and history, sessions, presets, home equipment, plus start/resume, performance logging, and completion
`client_ai_wod`	`health`	Today’s/date/detail WOD, verified leaderboard, preferences, plus safe preference, start, and completion writes

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.

​Client Portal Flow

​How It Differs

​Client AI Modules

​Consent

​Runtime Filtering

Client Portal Flow

How It Differs

Client AI Modules

Consent

Runtime Filtering