MCP protocol

How Swiggy speaks Model Context Protocol - transports, the session lifecycle, advertised capabilities, and the JSON-RPC methods you call.

Swiggy Builders Club exposes its four commerce servers as Model Context Protocol servers. MCP is an open standard: any conformant client or framework talks to Swiggy over the wire, with no bespoke SDK and no lock-in. This page is the canonical description of the protocol surface - what to connect to, how a session is established, and which JSON-RPC methods exist.

If you just want working code, see Connect with an MCP SDK (raw client) or Build an agent (frameworks).

Transports and endpoints

Swiggy MCP is served over Streamable HTTP - one URL per server, standard JSON-RPC 2.0. There is one endpoint per commerce domain:

ServerEndpoint
Swiggy FoodPOST https://mcp.swiggy.com/food
InstamartPOST https://mcp.swiggy.com/im
DineoutPOST https://mcp.swiggy.com/dineout
ScenesPOST https://mcp.swiggy.com/scenes

Each endpoint is an independent MCP server with its own tool list. Connect one session per server you use.

Session lifecycle

An MCP session follows the standard handshake. Your client SDK performs most of this for you:

  1. initialize - the client sends its supported protocol version and capabilities; the server replies with its serverInfo (name + version) and the capabilities it supports. The MCP SDKs in this guide (the 1.x line) speak the 2024/2025 revisions and settle on one with the server automatically over this handshake - Swiggy's servers support those revisions, so there is nothing to configure. The newer 2026-07-28 revision replaces the initialize handshake with per-request metadata; the 2.x-generation SDKs can use it where a server has enabled it, while the 1.x clients in this guide stay on the 2024/2025 initialize handshake.
  2. notifications/initialized - the client confirms it is ready.
  3. tools/list - discover the tools available to the signed-in user (this can be fewer than the full catalogue, or include beta tools).
  4. tools/call - invoke a tool with its arguments and read the result.

Authentication happens around this handshake: Swiggy MCP is OAuth 2.1 with PKCE, with Dynamic Client Registration and discovery documents - see Authenticate.

Advertised capabilities

At initialize, each Swiggy server advertises:

CapabilityStatusNotes
toolsActiveThe commerce tools for that server. Enumerate with tools/list, invoke with tools/call.
resourcesActive (widgets)Widget UI is served as MCP resources. resources/list + resources/read return the HTML for ui://widget/... URIs that widget-backed tools reference via _meta.ui.resourceUri. See Widgets.
promptsAdvertised, emptyAdvertised so clients that probe prompts/list or prompts/get get an empty result instead of a "method not found" error. Swiggy ships no server-side prompts today.

Methods you call

MethodPurpose
initializeStart the session; negotiate protocol version and capabilities.
tools/listList the tools available to the authenticated user.
tools/callInvoke a tool. Arguments follow each tool's inputSchema (see Reference).
resources/listList available widget resources.
resources/readFetch a widget's HTML by its ui://widget/... URI.
resources/templates/listReturns an empty list (no resource templates).
prompts/listReturns an empty list (no prompts shipped).
prompts/getReturns empty messages (no prompts shipped).

Reading results

Tool results arrive as MCP content. Read the structured payload from structuredContent, falling back to the JSON envelope in the first content block when that is missing - see Read tool results for the exact shape per server.

Errors

Protocol-level and auth failures surface as JSON-RPC errors (-32001 auth, -32603 internal, -32003 forbidden, -32000 too-many-requests), while tool-level failures use the { success: false, error } envelope. See Error codes for the full catalogue and how to classify each class.

Next