Local Sandbox

Build and test your agent against a local copy of Careem MCP. The sandbox is an MCP server that runs on your machine with the same tools, server identity and response shapes as production, answering from scenario files. It never calls Careem systems, never places a real order, and needs no client ID or credentials.

Rides tools are coming soon and aren't in the sandbox yet.

It ships as a no-code package: Markdown only. Your coding agent reads it and builds the server in the language you choose, then runs it at http://127.0.0.1:8787/mcp.

Quick start: let your coding agent build it

Paste this into Claude Code, Codex, Cursor or any coding agent that can run shell commands, and swap in the language you want:

Download https://builders.careem.com/sandbox/careem-mcp-sandbox.zip, unzip it, then read
careem-mcp-sandbox/README.md and follow it to build and run the Careem MCP sandbox in TypeScript.
When it's running, tell me the URL and how to connect my MCP client.

The agent builds the server in a new folder next to the package, implements the build spec with an official MCP SDK, runs its acceptance tests and starts the server. Expect a few hundred lines of code.

Get the package

• Download: careem-mcp-sandbox.zip
• Browse it online: every file is also served as plain Markdown, starting from README.md.

File	What it is
README.md	Instructions for the coding agent
spec/BUILD.md	Language-agnostic build spec, acceptance tests and client setup
spec/SCENARIOS.md	Every tool's scenarios and the arguments that trigger them
spec/FIXTURES.md	The test world: persona, addresses, restaurants, baskets and orders
spec/MCP_SERVER.md	Protocol and HTTP behaviour of the real server
spec/FORMAT.md	Format of a tool file, match rules and placeholders
spec/tools/<domain>/<tool>.md	One file per tool: notes, scenarios and the exact tool definition

Connect your client

Once the server is running:

Client	Setup
Claude Code	claude mcp add --transport http careem-mcp http://127.0.0.1:8787/mcp
Cursor / VS Code / Windsurf	{"mcpServers":{"careem-mcp":{"url":"http://127.0.0.1:8787/mcp"}}}
Claude Desktop	{"mcpServers":{"careem-mcp":{"command":"<your binary>","args":["--stdio"]}}}
Codex	[mcp_servers.careem-mcp] with command and args = ["--stdio"] in ~/.codex/config.toml
MCP Inspector	npx @modelcontextprotocol/inspector, then Streamable HTTP → http://127.0.0.1:8787/mcp
ChatGPT (developer mode)	Expose the server through an HTTPS tunnel (for example cloudflared tunnel --url http://127.0.0.1:8787) and use https://<tunnel>/mcp with no auth

No Authorization header is needed.

The test world

Every tool answers from one shared, made-up world, so multi-step journeys line up: search → options → add to cart → checkout, or Box config → quote → order.

User	Leonardo DiCappuccino, Dubai, currency AED
Saved places	Home LOC-50001 (Marina Gate 1, Dubai Marina), Work LOC-50002 (Emirates Towers), Gym LOC-50003
Payment	Visa •••• 4242 (preferred), Careem Wallet with AED 125.50, cash

The full list of ids, restaurants, menus, baskets and orders is in FIXTURES.md.

Trigger specific outcomes

Each tool has several scenarios: the happy path, empty results, validation errors and upstream failures. Pick one in either of two ways.

With arguments. The first scenario whose trigger matches the call wins; otherwise the default answers. A few triggers that work across tools:

Argument	Outcome
An id or text containing missing	Not found
Text containing trigger_upstream_down, merchant 99999 or restaurant 39999	Upstream unavailable
latitude: 0 with a non-zero longitude	Outside the service area
Food query containing xyz	No search results
cart_checkout with payment_type: "card", payment_id: 4000002	Card declined

SCENARIOS.md lists every scenario and its trigger.

By forcing it. The CLI your agent builds writes .run/overrides.json, which the server re-reads on every call, so there's no restart:

./careem-mcp.sh scenario cart_checkout payment-declined   # every cart_checkout call now declines
./careem-mcp.sh scenarios cart_checkout                   # list the scenarios for a tool
./careem-mcp.sh reset                                     # back to argument-based selection

Forcing happens outside MCP, so your agent sees exactly what it would see in production.

How it differs from production

• No OAuth. Connect without a token. In production, every call needs a Careem Identity access token; see Authentication.
• No state. Responses come from fixed scenarios: adding an item doesn't change what cart_get_basket returns, and nothing is ever booked or charged.
• Same contract. Tool names, descriptions, input and output schemas and the server identity match production, so moving over means changing the URL and adding OAuth.

Moving to production

1. Request a client ID for your use case.
2. Implement the OAuth flow and point your client at https://mcp.careemapis.com/mcp.
3. Keep confirming every ⚠️ mutating tool with the user. In production they place real orders and spend real money.