PostCartsIdShippingMethods

Add a shipping method to a cart when customers select their preferred shipping option during checkout.

Instructions

Add a shipping method to a cart. Use this API route when the customer chooses their preferred shipping option.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No
`fields`	No

Implementation Reference

src/services/medusa-store.ts:82-126 (handler)

The handler function for the PostCartsIdShippingMethods tool (and all store API tools). It parses input into query/body params based on OpenAPI parameters and executes the POST request via Medusa SDK to /carts/{id}/shipping-methods endpoint.

handler: async (
    input: InferToolHandlerInput<any, ZodTypeAny>
): Promise<any> => {
    const query = new URLSearchParams(input);
    const body = Object.entries(input).reduce(
        (acc, [key, value]) => {
            if (
                parameters.find(
                    (p) => p.name === key && p.in === "body"
                )
            ) {
                acc[key] = value;
            }
            return acc;
        },
        {} as Record<string, any>
    );
    if (method === "get") {
        console.error(
            `Fetching ${refPath} with GET ${query.toString()}`
        );
        const response = await this.sdk.client.fetch(refPath, {
            method: method,
            headers: {
                "Content-Type": "application/json",
                "Accept": "application/json",
                "Authorization": `Bearer ${process.env.PUBLISHABLE_KEY}`
            },
            query: query
        });
        return response;
    } else {
        const response = await this.sdk.client.fetch(refPath, {
            method: method,
            headers: {
                "Content-Type": "application/json",
                "Accept": "application/json",
                "Authorization": `Bearer ${process.env.PUBLISHABLE_KEY}`
            },
            body: JSON.stringify(body)
        });
        return response;
    }
}

src/services/medusa-store.ts:54-81 (schema)

Generates the Zod input schema for the tool based on the OpenAPI parameters from store.json spec for the POST /carts/{id}/shipping-methods operation.

inputSchema: {
    ...parameters
        .filter((p) => p.in != "header")
        .reduce((acc, param) => {
            switch (param.schema.type) {
                case "string":
                    acc[param.name] = z.string().optional();
                    break;
                case "number":
                    acc[param.name] = z.number().optional();
                    break;
                case "boolean":
                    acc[param.name] = z.boolean().optional();
                    break;
                case "array":
                    acc[param.name] = z
                        .array(z.string())
                        .optional();
                    break;
                case "object":
                    acc[param.name] = z.object({}).optional();
                    break;
                default:
                    acc[param.name] = z.string().optional();
            }
            return acc;
        }, {} as any)
},

src/index.ts:35-41 (registration)

Registers all dynamically generated tools, including PostCartsIdShippingMethods, with the MCP server.

tools.forEach((tool) => {
    server.tool(
        tool.name,
        tool.description,
        tool.inputSchema,
        tool.handler
    );

src/index.ts:15-17 (registration)
Calls defineTools() on MedusaStoreService to generate and collect the tool definitions, including the one for PostCartsIdShippingMethods.
```
    ...medusaStoreService.defineTools(),
    ...medusaAdminService.defineTools()
];
```

src/utils/define-tools.ts:16-60 (helper)

Utility that wraps the raw tool handler to conform to MCP protocol response format, used for all tools including PostCartsIdShippingMethods.

export const defineTool = (
    cb: (zod: typeof z) => ToolDefinition<any, ZodAny, any>
) => {
    const tool = cb(z);

    const wrappedHandler = async (
        input: InferToolHandlerInput<Zod.ZodAny, Zod.ZodAny>,
        _: RequestHandlerExtra
    ): Promise<{
        content: CallToolResult["content"];
        isError?: boolean;
        statusCode?: number;
    }> => {
        try {
            const result = await tool.handler(input);
            return {
                content: [
                    {
                        type: "text",
                        text: JSON.stringify(result, null, 2)
                    }
                ]
            };
        } catch (error) {
            return {
                content: [
                    {
                        type: "text",
                        text: `Error: ${
                            error instanceof Error
                                ? error.message
                                : String(error)
                        }`
                    }
                ],
                isError: true
            };
        }
    };

    return {
        ...tool,
        handler: wrappedHandler
    };
};

Medusa MCP Server