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 use the same OAuth flow, but the token’s aud must contain the surface’s resource: the API URL for REST, https://e2e.api.movmo.io/v1/mcp for MCP. A client onboarded for MCP receives both in one token; see Token audience.

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: call it from your backend. The one browser call is the Express Checkout button’s offer save, which gets CORS headers only for your registered origins and sends your apiKey from page JavaScript by design.

For a checkout UI launched from a partner page, use Express Checkout: the @movmo/express-checkout-button package (a React component or one script tag) sends the traveler to a Movmo-hosted checkout page and back to yours.