Skip to main content
FITsociety MCP uses a multi-layered security model to protect client and company data. All static API keys and OAuth connections map to a CompanyMcpGrant which defines their exact permissions. Static API keys are always company/coach grants. OAuth connections can be approved either by a Manager/Admin coach for company/coach access, or by the authenticated client for client MCP access. Both company/coach access and client MCP access are gated by the company MCP integration feature. Client MCP access is additionally gated by the client-company relationship, the client AI access toggle, and the company’s client MCP policy.

​
Company Scope Isolation

Every MCP credential is bound to a single company ID. The client cannot query or modify data belonging to any other company. There are no cross-company or global administrative endpoints available on the MCP server. Client AI grants add a second boundary: subjectType: "client" and subjectClientId. Those grants can only discover client_ai_* modules and their tools cannot switch to another client record. They also require the client AI access toggle to remain active for that company relationship, the company MCP integration feature to remain enabled, and the company client MCP policy to keep allowing the granted modules.
When a tool is listed (tools/list) or executed (tools/call), the server processes it through a series of permission filters:

​
1. Module Scoping

Tools are grouped into functional modules. The grant must list the module key (for example invoices, clients, or client_ai_nutrition) in its allowedModules array, otherwise all tools in that module are hidden and inaccessible. Client AI grants may only use explicit client_ai_* modules. Company/coach grants use the company-scoped modules. To comply with GDPR Article 9 (Special Category Data) and confidentiality requirements, certain modules require explicit opt-in consent from the approving coach or client:
  • Health Data Consent: Required to access modules categorized with health sensitivity. This includes measurements, intake forms, daily calorie intake logs, habits, checkup answers, goal settings, documents, nutrition logs, and matching client AI health modules.
  • Private Communication Consent: Required to access modules categorized with private_communication sensitivity. This includes chats, client notes, client documents, and client messages.

​
3. Read-Only Mode & Write Permissions

By default, all connections are read-only.
  • Write Tools: Tools that mutate database records, such as creating clients, bookings, calendar tasks, notes, recipes, nutrition plans/logs, or client AI entries, are classified as write tools.
  • Enabling Write Access: To execute a write tool, the grant must:
    1. Have read-only mode disabled (i.e. readOnly is false).
    2. Explicitly include the tool name (e.g. create_client) in its allowedWriteTools list.

​
Revocation & Expiration

  • Expiration: API keys and OAuth grants have a set lifetime. Once expired, all corresponding tokens immediately fail with a 401 Unauthorized status.
  • Company/coach revocation: A company manager or admin can revoke company/coach grants in the coach dashboard settings. Revoking a grant immediately invalidates the static API key and revokes all associated active OAuth access and refresh tokens.
  • Client AI revocation: A client can revoke only their own client-bound grants through POST /app/v1/client/mcp/grants/:grantId/revoke.

​
Owner Dependency Rule

Company/coach MCP grants are owned by the specific coach who created or approved them.
  • Active Check: During every tool execution, the server verifies that the owner coach is still active and holds the Manager or Admin role in that company.
  • Immediate Deactivation: If the owner coach’s role is demoted, their company access is removed, or their account is deactivated, all API keys and OAuth tokens under their grant instantly fail with a 403 Forbidden (COMPANY_MCP_GRANT_OWNER_INACTIVE) error code.
Client AI grants are not coach-owned. Their runtime check is the client subject binding; the tool context must match the approved subjectClientId.

​
Transparent Audit Logging

FITsociety records every tool call to a secure audit log table (CompanyMcpToolAuditLog) for review. To respect client privacy, argument values are never stored. The logs only record:
  • The tool name called.
  • The grant subject type and client subject when present.
  • The names of the argument keys provided (e.g. ["clientId", "firstName"]).
  • The execution status (success or error) and error codes.
  • The duration in milliseconds.
  • The IP address and client metadata of the caller.