Best practices

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.

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

• 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

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

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

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

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

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 page for detailed guidance.

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

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 documentation for specific limits.

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