# AI

> Configuration for AI Assistant and Model Context Protocol (MCP) features.

<partial content="config-env-vars">



</partial>

## AI Assistant

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        AI_ENABLED
      </code>
    </td>
    
    <td>
      Whether AI Assistant features are available. Set to <code>
        false
      </code>
      
       to completely disable AI Assistant across the entire instance, hiding the sidebar for all users and disabling the settings for administrators.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout color="info" icon="i-lucide-info">

When `AI_ENABLED` is set to `false`:

- The API routes for the assistant are not mounted
- AI Assistant sidebar is hidden from all users
- AI settings form displays a disabled notice

This is useful for compliance requirements where AI features must be completely hidden.

</callout>

## Model Context Protocol

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        MCP_ENABLED
      </code>
    </td>
    
    <td>
      Whether the Model Context Protocol server is available for system administrators to enable in project settings. Set to <code>
        false
      </code>
      
       to completely disable MCP functionality across the entire instance.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout color="info" icon="i-lucide-info">

When `MCP_ENABLED` is set to `false`, the MCP server cannot be enabled through **Settings → AI → Model Context Protocol** in the admin interface, providing system administrators with complete control over AI integration features. See the [MCP Server](/guides/ai/mcp/installation) guide for more information.

</callout>

## Model Context Protocol OAuth

MCP OAuth adds browser-based authorization for compatible MCP clients. Set `MCP_OAUTH_ENABLED` to `true` to mount the OAuth discovery, authorization, token, registration, and revocation routes.

Client registration modes are separately opt-in. Enable at least one registration mode with `MCP_OAUTH_DCR_ENABLED=true` for Dynamic Client Registration or `MCP_OAUTH_CIMD_ENABLED=true` for Client ID Metadata Document registration. Both the environment variable and project setting must allow a registration mode before Directus advertises or accepts it.

After enabling the environment variables, enable **OAuth Enabled** and at least one client registration mode in **Settings** > **AI** > **Model Context Protocol** for each project that should allow MCP OAuth.

The MCP OAuth authorization endpoint and Dynamic Client Registration endpoint use dedicated rate limiter pools. See [Security & Limits](/configuration/security-limits#rate-limiting) for the `RATE_LIMITER_MCP_OAUTH_*` and `RATE_LIMITER_MCP_OAUTH_REGISTRATION_*` variables.

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        MCP_OAUTH_ENABLED
      </code>
    </td>
    
    <td>
      Whether MCP OAuth routes are mounted. Set to <code>
        true
      </code>
      
       before enabling MCP OAuth in project settings.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_AUTH_CODE_TTL
      </code>
    </td>
    
    <td>
      How long an OAuth authorization code remains valid before the client exchanges it for tokens.
    </td>
    
    <td>
      <code>
        60s
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_MAX_CLIENTS
      </code>
    </td>
    
    <td>
      Maximum number of registered OAuth clients. Set to <code>
        0
      </code>
      
       to disable the limit.
    </td>
    
    <td>
      <code>
        10000
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CLIENT_UNUSED_TTL
      </code>
    </td>
    
    <td>
      How long an unused registered client can remain before cleanup removes it.
    </td>
    
    <td>
      <code>
        24h
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CLIENT_IDLE_TTL
      </code>
    </td>
    
    <td>
      How long an inactive registered client can remain after its last OAuth activity. Set to <code>
        0
      </code>
      
       to disable idle cleanup.
    </td>
    
    <td>
      <code>
        0
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_REQUIRE_RESOURCE
      </code>
    </td>
    
    <td>
      Whether authorization and refresh requests must explicitly include the MCP resource parameter.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CLEANUP_SCHEDULE
      </code>
    </td>
    
    <td>
      Cron schedule for removing expired authorization codes, expired OAuth grants, and stale clients.
    </td>
    
    <td>
      <code>
        */15 * * * *
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_ALLOWED_REDIRECT_DOMAINS
      </code>
    </td>
    
    <td>
      Comma-separated domain allowlist for HTTPS OAuth redirect URIs. Leave empty to allow any valid HTTPS redirect URI. Loopback redirects and configured custom-scheme redirects are allowed separately.
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_ALLOWED_CUSTOM_REDIRECTS
      </code>
    </td>
    
    <td>
      Comma-separated allowlist of custom URI-scheme redirect authorities for desktop MCP clients. Set to an empty value to disable custom-scheme redirects.
    </td>
    
    <td>
      <code>
        raycast://oauth,cursor://cursor.mcp
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_DCR_ENABLED
      </code>
    </td>
    
    <td>
      Whether Dynamic Client Registration can be enabled in project settings.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CIMD_ENABLED
      </code>
    </td>
    
    <td>
      Whether Client ID Metadata Document registration can be enabled in project settings.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CIMD_ALLOW_HTTP
      </code>
    </td>
    
    <td>
      Allow <code>
        http://
      </code>
      
       Client ID Metadata Document URLs. Keep disabled outside local development.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CIMD_ALLOWED_DOMAINS
      </code>
    </td>
    
    <td>
      Comma-separated list of domains allowed to use Client ID Metadata Document registration. Leave empty to allow any valid metadata document domain.
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_OAUTH_CIMD_BLOCKED_TLDS
      </code>
    </td>
    
    <td>
      Comma-separated list of top-level domains blocked for Client ID Metadata Document registration.
    </td>
    
    <td>
      <code>
        test,localhost,invalid,example,local,onion
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout color="primary" icon="i-lucide-book-open" to="/guides/ai/mcp/oauth">

Read the MCP OAuth guide for setup steps, client registration behavior, and revocation.

</callout>

## Telemetry

Send AI Assistant traces to an external observability platform for monitoring usage, performance, and cost.

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        AI_TELEMETRY_ENABLED
      </code>
    </td>
    
    <td>
      Enable OpenTelemetry-based tracing for AI Assistant requests. User IDs and Role ID will be included in traces.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AI_TELEMETRY_PROVIDER
      </code>
    </td>
    
    <td>
      Telemetry provider to use. Supported values: <code>
        langfuse
      </code>
      
      , <code>
        braintrust
      </code>
      
      .
    </td>
    
    <td>
      <code>
        langfuse
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AI_TELEMETRY_RECORD_IO
      </code>
    </td>
    
    <td>
      Include full prompt inputs and response outputs in traces.
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout color="warning" icon="i-lucide-triangle-alert">

Enabling `AI_TELEMETRY_RECORD_IO` will send the full content of user messages and AI responses to your telemetry provider. Only enable this if your telemetry provider meets your data privacy requirements.

</callout>

### Langfuse

Set `AI_TELEMETRY_PROVIDER` to `langfuse` (default).

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        LANGFUSE_SECRET_KEY
      </code>
    </td>
    
    <td>
      Langfuse secret key.
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LANGFUSE_PUBLIC_KEY
      </code>
    </td>
    
    <td>
      Langfuse public key.
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LANGFUSE_BASE_URL
      </code>
    </td>
    
    <td>
      Langfuse API base URL.
    </td>
    
    <td>
      <code>
        https://cloud.langfuse.com
      </code>
    </td>
  </tr>
</tbody>
</table>

### Braintrust

Set `AI_TELEMETRY_PROVIDER` to `braintrust`.

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        BRAINTRUST_API_KEY
      </code>
    </td>
    
    <td>
      Braintrust API key.
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BRAINTRUST_PROJECT_NAME
      </code>
    </td>
    
    <td>
      Braintrust project name for grouping traces.
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BRAINTRUST_API_URL
      </code>
    </td>
    
    <td>
      Braintrust API URL. Only needed for self-hosted instances.
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>