---
title: MCP OAuth
amsdal_docs:
  target: framework/plugins/amsdal-ml/mcp-oauth.md
  nav_title: OAuth
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML", "MCP Server"]
  nav_order: 3
---

# MCP OAuth

The MCP server supports OAuth 2.0 authentication, allowing MCP clients to authenticate as AMSDAL users with full permission checks.

## Overview

When OAuth is enabled, MCP clients must authenticate before accessing tools. The flow:

1. Client discovers OAuth endpoints via `/.well-known/oauth-protected-resource`
2. Client registers and receives a `client_id`
3. User is redirected to AMSDAL's login page
4. After login, client receives an authorization code
5. Client exchanges code for access + refresh tokens
6. Tokens are sent with each MCP request

All AMSDAL permission checks (class-level and object-level) are applied based on the authenticated user.

## Configuration

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `OAUTH_ENABLED` | `true` | Enable/disable OAuth for MCP |
| `OAUTH_CLIENT_ID_EXPIRATION_DAYS` | `30` | Client ID token expiration (days) |
| `OAUTH_CODE_EXP_MINUTES` | `10` | Authorization code expiration (minutes) |
| `OAUTH_ACCESS_TOKEN_EXP_HOURS` | `24` | Access token expiration (hours) |
| `OAUTH_REFRESH_TOKEN_EXP_DAYS` | `90` | Refresh token expiration (days) |
| `OAUTH_LOGIN_PATH` | `/auth/login` | Custom login page path |
| `OAUTH_ISSUER` | `http://127.0.0.1:8000` | Token issuer identifier |

## OAuth Endpoints

The following endpoints are mounted automatically when the plugin is registered:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/.well-known/oauth-protected-resource` | GET | Protected resource metadata |
| `/.well-known/oauth-authorization-server` | GET | Authorization server metadata |
| `/register` | POST | Client registration (returns `client_id`) |
| `/oauth/authorize` | GET | Authorization endpoint (redirects to login) |
| `/oauth/token` | POST | Token exchange (code → access/refresh tokens) |
| `/auth/login` | GET/POST | Login page for user authentication |

## PKCE Support

The OAuth flow uses PKCE (Proof Key for Code Exchange) with S256 challenge method for security. MCP clients that support OAuth (like Chatbox AI) handle PKCE automatically.

## Token Flow

```
Client                     AMSDAL Server
  |                              |
  |-- POST /register ----------->|  (get client_id)
  |<---- client_id --------------|
  |                              |
  |-- GET /oauth/authorize ----->|  (with PKCE challenge)
  |<---- redirect to login ------|
  |                              |
  |  [User logs in]              |
  |                              |
  |<---- authorization code -----|
  |                              |
  |-- POST /oauth/token -------->|  (code + PKCE verifier)
  |<---- access + refresh token -|
  |                              |
  |-- MCP request + Bearer ----->|  (authenticated)
  |<---- response ---------------|
```

## Auth Bridge

The `OAuthAuthenticateBridgeListener` translates OAuth bearer tokens into internal AMSDAL auth tokens. This ensures that:

- The MCP request runs in the context of the authenticated user
- All AMSDAL permission checks apply (class-level, object-level)
- Audit trails show the actual user, not a service account

## Token Refresh

When an access token expires, the client uses the refresh token to get a new pair:

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<token>&client_id=<id>
```

Refresh tokens are rotated on each use — a new refresh token is issued. Note that old refresh tokens remain valid until their natural JWT expiry.

## Disabling OAuth

For development or trusted environments, you can disable OAuth:

```bash
export OAUTH_ENABLED=false
```

Without OAuth, the MCP server is accessible without authentication. Use this only in development.
