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

# Best practices

> Optimize your Deel MCP integration for security, performance, and reliability

This page provides guidance for building production-ready integrations with the Deel MCP server. These recommendations apply whether you are configuring an off-the-shelf MCP client or building a custom integration.

## Security

#### Use OAuth2 when available

Prefer OAuth2 over personal access tokens for MCP authentication. OAuth2 provides:

* Scoped access limited to the permissions your application requires
* Automatic token rotation through refresh tokens
* User-level consent and the ability to revoke access without regenerating credentials

Use personal access tokens only when your MCP client does not support OAuth2.

#### Apply the principle of least privilege

Request only the scopes your application needs. Overly broad permissions increase the impact of a compromised token.

* Review the scopes required by each tool before requesting them
* Separate read and write scopes where possible (for example, `contracts:read` instead of `contracts:read contracts:write` if you only need to view contracts)
* Audit granted scopes periodically and remove any that are no longer required

#### Store tokens securely

* Encrypt access tokens and refresh tokens at rest
* Never store tokens in version control, client-side code, or browser local storage
* Use environment variables or a dedicated secrets manager
* Implement token revocation when a user disconnects or the integration is removed

#### Handle refresh token rotation correctly

Refresh tokens are single-use. After each token refresh, store the new refresh token and discard the old one. Failing to update the stored token results in `invalid_grant` errors on the next refresh attempt.

For full details on token rotation, see the [OAuth2 token rotation](/api/oauth#token-rotation) documentation.

## Performance

#### Reuse connections

The Deel MCP server supports persistent HTTP connections. Reusing connections avoids the overhead of repeated TLS handshakes and reduces latency for sequential tool invocations.

* Keep HTTP connections alive between requests
* Use connection pooling if your client supports it
* Avoid opening a new connection for each tool invocation

#### Handle SSE reconnection

The MCP server uses Server-Sent Events (SSE) for streaming responses. If the SSE connection drops:

* Reconnect automatically with exponential backoff
* Start with a 1-second delay, doubling on each attempt up to a maximum of 30 seconds
* Re-authenticate if the reconnection receives a 401 response

#### Select tools efficiently

The Deel MCP server exposes a large number of tools. To reduce latency and improve AI agent performance:

* Use specific prompts that guide the agent toward the correct tool
* Provide context about the type of data you need (for example, "list my EOR contracts" rather than "show me everything")
* Be aware that broad prompts may cause the agent to invoke multiple tools sequentially

## Reliability

#### Implement error handling

Build resilience into your integration by handling errors at every level:

* **HTTP errors**: Implement retry logic with exponential backoff for 429, 500, 502, and 503 responses
* **JSON-RPC errors**: Validate requests before sending to avoid -32600 and -32602 errors
* **Tool execution errors**: Check the `isError` flag in tool responses and handle failures gracefully

See the [error handling](/mcp/error-handling) page for detailed guidance.

#### Monitor token expiration

Access tokens are valid for 1 hour and refresh tokens for 30 days. Proactively refresh access tokens before they expire to avoid service interruptions.

* Track the `expires_in` value returned with each token response
* Refresh access tokens before the 1-hour expiry — most clients handle this automatically
* Alert on repeated refresh failures, which may indicate a revoked grant

#### Handle rate limits gracefully

The Deel MCP server enforces the same rate limits as the Deel REST API.

* Respect the `Retry-After` header on 429 responses
* Implement client-side rate limiting to stay within known thresholds
* Distribute requests over time rather than sending bursts

See the [rate limits](/api/rate-limits) documentation for specific limits.

#### Log and audit tool invocations

For production integrations, log tool invocations to support debugging and compliance:

* Record the tool name, input parameters (excluding sensitive data), and response status for each invocation
* Track error rates and latency to identify issues early
* Audit which tools are used and by whom to ensure appropriate access patterns

## Next steps

#### [Authorization](/mcp/authorization)

Configure OAuth2 or bearer token authentication

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

Browse the full list of available MCP tools

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

Handle errors when invoking MCP tools

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

Learn about OAuth2 authentication for the Deel API