Your agent needs to hire, pay, or manage people through Deel. Deel now ships two ways to get there: an official Model Context Protocol (MCP) server at api.letsdeel.com/mcp, and the REST API that the MCP server is built on top of. They are not interchangeable. They put your agent on different auth paths, expose different operational surface area, and behave differently under a multi-tenant load. Picking the wrong one shows up later, in production, when a nightly job has no browser to complete a consent flow or a payment quietly retries twice. Here is how to choose.
Both are official and Deel-maintained. The distinction that matters for an agent is not what each can do, but how your agent authenticates and what it has to own around each one.
Deel's MCP server is a vendor MCP: built and maintained by Deel, reachable at api.letsdeel.com/mcp. It communicates over HTTP using JSON-RPC 2.0 with Server-Sent Events for streaming, and each tool maps directly to a Deel API operation. Tools are grouped into three permission levels: Organization (org-wide data, org-level scopes), Worker (scoped to a single worker, worker-level auth), and Public (reference data such as countries and currencies). Authentication is OAuth2 (OAuth 2.1 with Dynamic Client Registration), with a personal access token fallback for clients that do not support OAuth. See the official Deel MCP server docs for the current tool categories.
The Deel REST API is the full workforce platform surface, hosted at api.letsdeel.com and versioned by date, with 2026-01-01 as the current stable version. It spans platform, employer of record, contractors, global payroll, HR, embedded, and Deel IT, plus webhooks for real-time events. Authentication uses bearer tokens: three API token variants (organization, personal, and worker) plus OAuth2 for user-authorized apps. Scopes follow a {resource}:read and {resource}:write pattern. See the official Deel API docs for the endpoint reference.
The comparison is not about which one is more capable. It is about the auth path each one forces, the surface area you inherit, and where each one quietly fails under production load. Four dimensions decide it.
Because every MCP tool wraps an API operation, the read and write coverage overlaps heavily: contracts, time off, payroll, ATS, compensation bands, EOR cost estimates, and worker documents are all reachable from either path. The gaps appear at the structural layer, where the API exposes controls the MCP tool interface does not.
The two gaps that hurt most in production are events and idempotency. If your agent needs to react when a contract is signed or a payment status changes, that requires webhooks, and the MCP surface has no event subscription. If your agent moves money, the Idempotency-Key header protects against a double payment on retry, and that header is an API-level control the MCP tool schema does not expose.
Deel MCP is user-centric by design. The recommended flow is OAuth2 browser consent, after which every tool call runs as the authenticated user, constrained to the Organization, Worker, and Public scopes that user was granted. A personal access token is the documented fallback for clients that cannot run OAuth.
The API opens up two credential shapes the MCP path does not. Organization tokens represent the whole org, are generated in the Developer Center, do not expire, and are built for server-to-server automation with no user in the loop; they cannot sign contracts. Worker tokens represent a single EOR worker, are minted programmatically through the create-worker-access-token endpoint under the Embedded model, and only reach worker-side paths. The multi-tenant credential fallout of either path gets its own section below.
The MCP path manages real work for you: schemas for hundreds of operations, endpoint normalization, OAuth discovery with Dynamic Client Registration, and request routing. When Deel changes an operation, the vendor server updates the tool and your agent picks it up without a redeploy. What it does not manage is the credential layer: token storage, refresh on the 30-day expiry, revocation on disconnect, and tenant isolation.
The direct API means you own the whole stack: endpoint selection across seven product areas, request construction with Deel's nested data wrappers, error handling, rate limits, idempotency, and token lifecycle. The tradeoff is control. The MCP tool surface is server-managed and effectively unversioned; the API is date-versioned, so you pin 2026-01-01 and opt into changes deliberately.
The choice tracks one question: is a person present when the agent runs? Interactive, conversational Deel work fits MCP. Headless, event-driven, or money-moving work fits the API.
Use Deel MCP when:
Use the Deel API when:
Whether you chose MCP or the API, every customer in a multi-tenant Deel agent holds their own credential. The MCP OAuth flow gives you a token per user; the API's Authorization Code path (RFC 6749) gives you an access token per user. Fifty customers means fifty grants, fifty token lifecycles, and fifty revocation paths to honor.
Deel's OAuth2 access tokens expire after 30 days and refresh tokens rotate, so refresh handling is mandatory; waiting for a 401 to trigger it invites the retry storms that break background execution. Organization tokens never expire, which is convenient until one leaks and becomes a standing liability with a wide blast radius. In every case the credential must live somewhere encrypted at rest, isolated per tenant, and revocable on disconnect. The token type differs by path; the infrastructure required is identical.
Authentication has to be built into the infrastructure, not integrated per connector. Scalekit's Deel connector runs the OAuth 2.1 flow, stores credentials in a token vault so they never touch your agent runtime, and refreshes and rotates them automatically. The MCP vs API decision no longer changes what you build for auth.
Recommended reading: Token vault for AI agent workflows and when to use a Virtual MCP server.
Scalekit ships Deel as a vendor-MCP connector named deelmcp. You resolve a per-user identifier from your own authenticated session, and Scalekit handles consent, token custody, scoped tool discovery, and execution. The pattern below follows the order that matters: connect, discover the authorized surface, then run the loop.
The one-time connection is triggered from your app using the current user's identifier. Never accept an identifier from the client; resolve it from your session, JWT, or database.
Before showing any code, the key idea: the agent is not loading a flat catalog of every Deel tool. It loads the tools the current user's connected account is authorized to call. list_scoped_tools returns that identity-scoped surface in Anthropic's native format, so there are no schemas to write.
This is the standard Anthropic tool-use loop. Claude decides what to call; your code executes each call through execute_tool with the user's identifier, so Scalekit reaches Deel as that user. The token never enters your code.
For that prompt, Claude resolves to deelmcp_contract_list and reasons over the result. The same connected-account pattern plugs into other frameworks; the Scalekit LangChain example exposes the same scoped tools through actions.langchain.get_tools, which calls list_scoped_tools under the hood.
Identity scoping is necessary but not sufficient. Deel's connector surfaces 355 tools, and a broad OAuth grant can leave most of them authorized. Handing an LLM that full surface is both an accuracy and a cost problem: at roughly 200 tokens per definition, 355 tools burn about 71,000 tokens before the agent does any work, and tool selection degrades when the decision space is that large.
A Virtual MCP server fixes this with explicit allow-listing: one server per agent role, exposing only the tools that role needs, such as deelmcp_contract_list and deelmcp_contract_termination_create for an offboarding agent. The agent sees only the tools you allow. One definition serves every user, and a short-lived session token is minted per run, so there is no server to deploy or maintain.
A Deel agent moves contracts, payments, and worker data, so observability is not optional. Scalekit's auth logs record every downstream tool call: which identity acted, which tool ran, and the result. That gives you the audit trail a security review will ask for, and the trace you need when a run misbehaves at 3am. What the user cannot do, the agent cannot do, and every action it does take is queryable after the fact.
The answer follows the shape of your agent, and most production Deel agents end up running both modes in the same product.
Interactive, user-present assistants belong on the MCP path. Tool discovery is handled, consent happens once, and you are operational quickly. This is the right foundation for conversational HR and finance agents where a human is there to authorize and review.
Headless, event-driven, money-moving, or version-pinned pipelines belong on the API. Organization tokens remove the user from the loop, webhooks give you events, the Idempotency-Key header protects writes, and date-based versioning keeps the pipeline deterministic. Either way, the credential problem is identical, and that is what needs production-grade infrastructure rather than another custom integration.
Whichever path fits, Scalekit is the auth and tool-calling layer underneath it. Start from the connector, then wire in the HR agent patterns you actually plan to ship.
Browse the Scalekit Deel connector docs and the Deel connector page, or see the full connector catalog. For starting points, look at the new hire provisioning agent, the offer letter routing agent, the PTO leave request agent, and the performance review collector agent. Pricing is on the pricing page.
Join other Deel agent builders in the Scalekit Slack community, or use the Talk to us page for immediate help wiring up per-user Deel auth.
