Get Started

Authorization

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

MethodWhen to useClient support
OAuth2Recommended 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. This flow uses a discovery-based approach where the client automatically locates the authorization server and registers itself before requesting user authorization.

Flow overview

Step-by-step flow

1

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.

2

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.

3

Fetch authorization server metadata

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

GET https://app.deel.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
4

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 section for the full request and response format.

5

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.

6

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)
7

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

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

Request body:

FieldTypeRequiredDescription
client_namestringYesDisplay name for the client application (maximum 150 characters)
redirect_urisstring[]YesArray of redirect URIs for the authorization callback (minimum 1)
grant_typesstring[]YesMust include authorization_code
response_typesstring[]YesMust include code
token_endpoint_auth_methodstringNoAuthentication method for the token endpoint. Use none for public clients with PKCE
code_challenge_methodstringNoPKCE code challenge method. Use S256
application_typestringNoweb or native
client_uristringNoURL of the client application homepage
logo_uristringNoURL of the client application logo
client_descriptionstringNoDescription of the client application

Example request:

1{
2  "client_name": "My MCP Client",
3  "redirect_uris": ["http://localhost:8080/callback"],
4  "grant_types": ["authorization_code"],
5  "response_types": ["code"],
6  "token_endpoint_auth_method": "none",
7  "code_challenge_method": "S256",
8  "application_type": "native"
9}

Example response:

1{
2  "client_id": "abc123def456",
3  "client_name": "My MCP Client",
4  "redirect_uris": ["http://localhost:8080/callback"],
5  "grant_types": ["authorization_code"],
6  "response_types": ["code"],
7  "token_endpoint_auth_method": "none"
8}

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

2

Generate an API token

Select Generate token to create a new personal access token.

3

Configure your MCP client

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

1{
2  "mcpServers": {
3    "deel": {
4      "url": "https://api.letsdeel.com/mcp",
5      "headers": {
6        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
7      }
8    }
9  }
10}

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 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:

ScopeAccess level
contracts:readRead contract data
contracts:writeCreate and modify contracts
people:readRead people and HRIS data
timesheets:readRead timesheet data
timesheets:writeCreate and modify timesheets
invoice-adjustments:readRead invoice adjustments
invoice-adjustments:writeCreate and modify invoice adjustments

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

Configure your AI client to connect to the Deel MCP server

Tools reference

Browse the full list of available MCP tools

OAuth2

Learn about OAuth2 authentication for the Deel API

Error handling

Handle authentication errors and other failure modes