> This page is for MCP Server.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Authorization

> Authenticate with the Deel MCP server using OAuth2 or bearer tokens

The Deel MCP server supports two authentication methods: OAuth2 with dynamic client registration (recommended) and bearer token authentication using a personal access token (PAT). Most MCP clients handle OAuth2 automatically, but this page describes the full flow for developers building custom integrations.

## Authentication methods

| Method                 | When to use                                                                                                           | Client support                           |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **OAuth2**             | Recommended for all clients that support it. Handles discovery, registration, and token management automatically.     | Cursor, VS Code, Claude Desktop, ChatGPT |
| **Bearer token (PAT)** | Fallback for clients that do not support OAuth. Requires manually generating and configuring a personal access token. | Any HTTP-capable client                  |

## OAuth2 authorization flow

The Deel MCP server implements the OAuth2 authorization flow defined by the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). This flow uses a discovery-based approach where the client automatically locates the authorization server and registers itself before requesting user authorization.

### Flow overview

```mermaid
sequenceDiagram
    participant Client as MCP Client
    participant MCP as Deel MCP Server
    participant PRM as Protected Resource Metadata
    participant ASM as Authorization Server Metadata
    participant AS as Authorization Server
    participant User

    Client->>MCP: tools/list or initialize (unauthenticated)
    MCP-->>Client: Success (public tools accessible)
    Client->>MCP: tools/call (protected operation, no token)
    MCP-->>Client: 401 Unauthorized (WWW-Authenticate header)
    Client->>PRM: GET /.well-known/oauth-protected-resource/mcp
    PRM-->>Client: Resource metadata (authorization server URL)
    Client->>ASM: GET /.well-known/oauth-authorization-server
    ASM-->>Client: Server metadata (endpoints, supported flows)
    Client->>AS: POST /register (dynamic client registration)
    AS-->>Client: Client credentials (client_id)
    Client->>AS: GET /authorize (with PKCE challenge)
    AS->>User: Show consent screen
    User->>AS: Approve access
    AS-->>Client: Authorization code
    Client->>AS: POST /token (exchange code)
    AS-->>Client: Access token + refresh token
    Client->>MCP: MCP request with Bearer token
    MCP-->>Client: MCP response
```

### Step-by-step flow

#### Connect to the MCP server

Public MCP operations such as `initialize` and `tools/list` are accessible without authentication. The server returns a `401 Unauthorized` response with a `WWW-Authenticate` header only when the client attempts to invoke a protected tool without a valid access token.

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.letsdeel.com/.well-known/oauth-protected-resource/mcp"
```

When this happens, the client begins the authorization flow described in the steps below.

#### Discover the protected resource metadata

The client fetches the protected resource metadata to identify which authorization server protects the MCP resource.

```
GET https://api.letsdeel.com/.well-known/oauth-protected-resource/mcp
```

The response contains the resource identifier, the authorization server URL, and the supported scopes for MCP access.

#### Fetch authorization server metadata

The client retrieves the authorization server metadata from the URL provided in the previous step.

```
GET https://api.letsdeel.com/.well-known/oauth-authorization-server
```

This metadata document describes the authorization server capabilities, including:

* Authorization endpoint
* Token endpoint
* Registration endpoint (for dynamic client registration)
* Supported grant types and response types
* Supported code challenge methods (PKCE)
* Available scopes

#### Register the client dynamically

If the MCP client does not already have a client ID registered with this authorization server, it registers itself using the OAuth2 Dynamic Client Registration Protocol (RFC 7591). The client sends a registration request to the registration endpoint discovered in the previous step.

This step happens automatically for most MCP clients. See the [dynamic client registration details](#dynamic-client-registration-details) section for the full request and response format.

#### Request user authorization

The client redirects the user to the authorization endpoint with a PKCE code challenge (S256 method). The user sees a consent screen showing the requested permissions and approves or denies access.

After approval, the authorization server redirects the user back to the client with an authorization code.

#### Exchange the authorization code for tokens

The client exchanges the authorization code for an access token and refresh token by sending a POST request to the token endpoint with the PKCE code verifier.

The response includes:

* **Access token**: Used to authenticate MCP requests (valid for 1 hour)
* **Refresh token**: Used to obtain new access tokens (valid for 30 days, single-use)

#### Make authenticated MCP requests

The client includes the access token in the `Authorization` header for all subsequent MCP requests.

```
Authorization: Bearer <access_token>
```

### Dynamic client registration details

#### Registration request and response

The client sends a POST request to the registration endpoint with the following fields:

**Request body:**

| Field                        | Type       | Required | Description                                                                           |
| ---------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- |
| `client_name`                | `string`   | Yes      | Display name for the client application (maximum 150 characters)                      |
| `redirect_uris`              | `string[]` | Yes      | Array of redirect URIs for the authorization callback (minimum 1)                     |
| `grant_types`                | `string[]` | Yes      | Must include `authorization_code`                                                     |
| `response_types`             | `string[]` | Yes      | Must include `code`                                                                   |
| `token_endpoint_auth_method` | `string`   | No       | Authentication method for the token endpoint. Use `none` for public clients with PKCE |
| `code_challenge_method`      | `string`   | No       | PKCE code challenge method. Use `S256`                                                |
| `application_type`           | `string`   | No       | `web` or `native`                                                                     |
| `client_uri`                 | `string`   | No       | URL of the client application homepage                                                |
| `logo_uri`                   | `string`   | No       | URL of the client application logo                                                    |
| `client_description`         | `string`   | No       | Description of the client application                                                 |

**Example request:**

```json
{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "code_challenge_method": "S256",
  "application_type": "native"
}
```

**Example response:**

```json
{
  "client_id": "abc123def456",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

> **Note**
>
> Public clients (those using `token_endpoint_auth_method: "none"`) must use PKCE with the S256 code challenge method to secure the authorization flow.

## Bearer token authentication

For MCP clients that do not support OAuth2, you can authenticate using a personal access token (PAT) passed in the `Authorization` header.

### Generate a personal access token

#### Navigate to your Deel dashboard

Go to **More** > **Developer** > **Apps** in your Deel dashboard.

#### Generate an API token

Select **Generate token** to create a new personal access token.

#### Configure your MCP client

Pass the token in the `Authorization` header when configuring your MCP client:

```json
{
  "mcpServers": {
    "deel": {
      "url": "https://api.letsdeel.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}
```

> **Warning**
>
> Store your personal access token securely. Do not commit tokens to version control or expose them in client-side code. Use environment variables or a secrets manager.

## Token management

Access tokens issued through the OAuth2 flow are valid for **1 hour**. Refresh tokens are valid for **30 days** and are **single-use** — each refresh exchange invalidates the previous refresh token and returns a new one.

Most MCP clients handle token refresh automatically. If you are building a custom client, refer to the [OAuth2 token rotation](/api/oauth#token-rotation) documentation for implementation details.

## Scopes

The scopes required for MCP tool access correspond to the scopes defined for the underlying Deel API endpoints. When a tool is invoked, the MCP server verifies that the access token includes the necessary scopes for the requested operation.

Common scope patterns for MCP tools:

| Scope                       | Access level                          |
| --------------------------- | ------------------------------------- |
| `contracts:read`            | Read contract data                    |
| `contracts:write`           | Create and modify contracts           |
| `people:read`               | Read people and HRIS data             |
| `timesheets:read`           | Read timesheet data                   |
| `timesheets:write`          | Create and modify timesheets          |
| `invoice-adjustments:read`  | Read invoice adjustments              |
| `invoice-adjustments:write` | Create and modify invoice adjustments |

> **Tip**
>
> Request only the scopes your application requires. Follow the principle of least privilege to minimize the impact of a compromised token.

## Next steps

#### [Connecting clients](/mcp/connecting-clients)

Configure your AI client to connect to the Deel MCP server

#### [Tools reference](/mcp/reference/tools-reference)

Browse the full list of available MCP tools

#### [OAuth2](/api/oauth)

Learn about OAuth2 authentication for the Deel API

#### [Error handling](/mcp/error-handling)

Handle authentication errors and other failure modes