> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Grants & Permissions

> Understand permission filters, GDPR compliance, consent, and audit logs.

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.

***

## Permissions & Consent Filters

When a tool is listed (`tools/list`) or executed (`tools/call`), the server processes it through a series of permission filters:

```mermaid theme={null}
graph TD
    A[Tool Request] --> M{Company MCP feature enabled?}
    M -- No --> Reject[Reject / Omit Tool]
    M -- Yes --> S{Client subject?}
    S -- Yes --> T{Module is client AI?}
    T -- No --> Reject[Reject / Omit Tool]
    T -- Yes --> U{Client AI enabled?}
    U -- No --> Reject
    U -- Yes --> V{Allowed by company client policy?}
    V -- No --> Reject
    V -- Yes --> B{Module in allowedModules?}
    S -- No --> B
    B -- No --> Reject[Reject / Omit Tool]
    B -- Yes --> C{Sensitivity: Health?}
    C -- Yes --> D{Health consent accepted?}
    D -- No --> Reject
    C -- No --> E{Sensitivity: Private Comm?}
    E -- Yes --> F{Private communication consent accepted?}
    F -- No --> Reject
    E -- No --> G{Is it a Write Tool?}
    D -- Yes --> G
    F -- Yes --> G
    G -- No --> Allow[Allow Tool]
    G -- Yes --> H{Grant Read-Only?}
    H -- Yes --> Reject
    H -- No --> I{Tool in allowedWriteTools?}
    I -- No --> Reject
    I -- Yes --> Allow
```

### 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.

### 2. Sensitivity & GDPR Consent

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.