REST vs. MCP

If your application is an LLM-orchestrated agent, use the Model Context Protocol (MCP). If it is a deterministic backend service, use REST. Both hit the same handlers — the choice is about the calling pattern, not the capability surface.

Decision table

Concern	REST	MCP
Orchestrator	Your code	An LLM calling tools
Transport	HTTPS over API Gateway	Streamable HTTP at https://e2e.api.movmo.io/v1/mcp (partners). stdio is reserved for local agent hosts like Claude Desktop.
Schema discovery	OpenAPI 3.1 spec at /openapi.yaml	tools/list JSON-RPC call against the running server; OAuth metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource
Best fit	Partner backends, batch jobs	Conversational agents
Auth header	x-api-key + Authorization: Bearer <access_token>	Authorization: Bearer <access_token> only

Header rules

REST and MCP authenticate differently. Mixing them on the same request triggers a 429:

• REST calls carry both x-api-key (your partner key) and Authorization: Bearer <access_token> (the user’s OAuth token). The API key authenticates the partner application; the Bearer authenticates the user.
• MCP calls carry only Authorization: Bearer <access_token>. Do not send x-api-key. Partner usage plans (Aviare, Customer, Public Website) throttle keyed traffic on /v1/mcp/* to 0 RPS — a safety net that returns 429 when the API key leaks onto an MCP call.
• Both surfaces accept the same access_token from the same OAuth flow. The user’s identity travels in the JWT.

Recommendation for agent-orchestrated apps

Use MCP for the booking flow — tool schemas keep the LLM grounded, and the agent never holds an API Gateway key. Use REST for back-office work that doesn’t involve a user conversation: reconciliation, reporting exports, admin syncs, batch processing.

It is normal to use both: booking flow on MCP, out-of-band reconciliation on REST. The user, data, and auth model are the same; you are choosing where each call originates.

Why not call REST from a browser

Movmo’s REST surface is a server-to-server contract. CORS is not opened to partner domains — allowed origins are limited to Movmo-hosted surfaces — and the API Gateway key is not safe in shipped JavaScript. Hold the key in your backend’s secret store and proxy calls through your own service.

For an embedded UI on a partner page, use @movmo/express-checkout-button, which embeds a Movmo-hosted iframe.