AWS marketplace: Document MCP session ID requirements and error handling
Summary
Clarifies that the MCP server issues an Mcp-Session-Id during initialize and requires it on later requests, documents HTTP 400/404 session errors, updates protocol/error examples, and reorganizes error categories and tool descriptions.
Security assessment
The change documents MCP session identifier issuance, required header usage, and 400/404 error behavior for missing, malformed, unknown, or expired session IDs. This is security-adjacent session handling, but there is no evidence it addresses a specific vulnerability, CVE, authentication, authorization, or encryption issue.
Evidence
+**Session identifier:** This server uses MCP sessions, as defined by the Streamable HTTP transport in the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), version 2025-06-18. The response to `initialize` includes an `Mcp-Session-Id` header, and MCP clients send it on every later request. If you build requests yourself, you must send it too. Requests without the header fail with HTTP 400. Requests fail with HTTP 404 if the identifier was not issued by the server, or if it has expired. If you receive a 404, call `initialize` again.
Diff
diff --git a/marketplace/latest/developerguide/marketplace-mcp-server.md b/marketplace/latest/developerguide/marketplace-mcp-server.md index 1f14a9d..9efacc0 100644 --- a//marketplace/latest/developerguide/marketplace-mcp-server.md +++ b//marketplace/latest/developerguide/marketplace-mcp-server.md @@ -64 +64 @@ The following are common ways to use the AWS Marketplace MCP server: -All 6 tools are stateless and require no conversation context or session management. All tool definitions, including full input/output schemas, are available programmatically through the standard MCP `tools/list` endpoint. The schemas returned by `tools/list` are the canonical, always-current source of truth for parameter names, types, and constraints. +All 6 tools are stateless and require no conversation context. All tool definitions, including full input/output schemas, are available programmatically through the standard MCP `tools/list` endpoint. The schemas returned by `tools/list` are the canonical, always-current source of truth for parameter names, types, and constraints. @@ -147,0 +148,5 @@ The following methods are supported: +**Session identifier:** This server uses MCP sessions, as defined by the Streamable HTTP transport in the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), version 2025-06-18. The response to `initialize` includes an `Mcp-Session-Id` header, and MCP clients send it on every later request. If you build requests yourself, you must send it too. Requests without the header fail with HTTP 400. Requests fail with HTTP 404 if the identifier was not issued by the server, or if it has expired. If you receive a 404, call `initialize` again. + + + Mcp-Session-Id: <stable-id> + @@ -210,16 +214,0 @@ Each tool entry includes the tool `name`, a detailed `description` with usage gu -#### Step 3: Configure telemetry - -AWS Marketplace MCP requires a stable identifier on every tool call for request correlation and telemetry. This is not an authentication credential — it is used only for diagnostics and analytics. - -Pass the identifier in the custom HTTP header: - - - Mcp-Session-Id: <stable-id> - - * **Browser clients:** Derive from an existing session cookie or a frontend-generated UUID. Use the same value across all tool calls. - - * **Programmatic clients:** Use `POST` with `method: "initialize"` to obtain an `Mcp-Session-Id`. - - - - @@ -236 +225 @@ The following are key transport characteristics: - * **Session management:** Session IDs through the `Mcp-Session-Id` header for request correlation and telemetry. + * **Session management:** The server issues an identifier in the response to `initialize`. Send it in the `Mcp-Session-Id` header on every later request. @@ -238 +227 @@ The following are key transport characteristics: - * **Protocol version:** Specified through the `MCP-Protocol-Version: 2025-06-18` header. + * **Protocol version:** The server supports [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18) version 2025-06-18. @@ -247 +236,2 @@ The following are key transport characteristics: - Mcp-Session-Id: <stable-uuid> + Accept: application/json, text/event-stream + Mcp-Session-Id: <stable-id> @@ -257 +247,2 @@ The following example shows a tool call request and response. - Mcp-Session-Id: 1868a90c-5b12-4e8a-9f3d-2a1b3c4d5e6f + Accept: application/json, text/event-stream + Mcp-Session-Id: 00000000-0000-0000-0000-000000000000 @@ -285 +276,4 @@ The following example shows a tool call request and response. - "isError": false + "structuredContent": { + "results": [...], + "next_cursor": null + } @@ -340 +334 @@ Field | Type | Description -Performs a direct AWS Marketplace Catalog API search. Returns raw, unranked, unfiltered results without AI processing or relevance scoring. Supports batch queries (up to 10) and cursor-based pagination for single queries. +Searches AWS Marketplace and returns a list of relevant solutions based on the user's queries. Supports batch queries (up to 10) and cursor-based pagination for single queries. @@ -393 +387 @@ Field | Type | Description -Performs a direct AWS Marketplace Catalog API call. Retrieves comprehensive solution metadata by solution ID without AI processing. Supports batch requests (up to 10 IDs). +Retrieves comprehensive solution metadata by solution ID, including reviews, pricing options, and call-to-action links. Supports batch requests (up to 10 IDs). @@ -493 +487 @@ Field | Type | Description -Performs a direct AWS Marketplace Catalog API call. Returns related solutions for given solution IDs as identified by AWS Marketplace, sorted by relation score (descending), without AI analysis or relevance scoring. Supports batch requests (up to 10 IDs). +Returns related solutions for given solution IDs as identified by AWS Marketplace, sorted by relation score (descending). Supports batch requests (up to 10 IDs). @@ -535 +529,3 @@ Field | Type | Description -`results[].related_solutions`| MinimalSolutionMetadata[]| Related solutions sorted by relevance. +`results[].related_solutions`| MinimalSolutionMetadata[]| Related solutions sorted by relation score (descending). + +If a solution ID has no related solutions, its `related_solutions` array is empty. Related solutions that are no longer listed are omitted. @@ -563 +559 @@ Section | What it returns -`reviews`| G2, Gartner, TrustRadius customer feedback +`reviews`| G2 and PeerSpot customer reviews @@ -616 +612 @@ Submits user feedback about an AWS Marketplace report. Call this tool after comp - "categories": ["incomplete", "other"], + "categories": ["Incomplete", "Other"], @@ -625 +621 @@ Field | Type | Required | Description -`categories` | string[] | No | For negative feedback: `"irrelevant"`, `"incomplete"`, `"inaccurate"`, `"other"`. +`categories` | string[] | No | For negative feedback: `"Irrelevant"`, `"Incomplete"`, `"Inaccurate"`, `"Other"`. @@ -650 +646 @@ This is the primary workflow for AI-assisted product research. It uses `get_aws_ - 3. The AI assistant follows the returned instructions, which typically involve calling catalog API and research tools to gather data. + 3. The AI assistant follows the returned instructions, which typically involve calling the search, solution-detail, and research tools to gather data. @@ -704 +700 @@ This is the primary workflow for AI-assisted product research. It uses `get_aws_ -For programmatic integrations or quick lookups that don't require AI analysis, you can call the catalog API tools directly without `get_aws_marketplace_report_guidelines`. +For programmatic integrations or quick lookups that don't require AI analysis, you can call the search, solution-detail, and related-solutions tools directly without `get_aws_marketplace_report_guidelines`. @@ -725 +721 @@ After completing any workflow, the assistant should collect user feedback. - 3. If negative, ask which categories apply (`irrelevant`, `incomplete`, `inaccurate`, `other`), optionally collect free-text feedback, and submit. + 3. If negative, ask which categories apply (`Irrelevant`, `Incomplete`, `Inaccurate`, `Other`), optionally collect free-text feedback, and submit. @@ -798 +794 @@ The following example demonstrates a complete recommendations workflow from init -Errors fall into three categories: protocol errors, tool execution errors, and validation errors. +Errors fall into three categories: protocol errors, input validation errors, and tool execution errors. @@ -802 +798,16 @@ Errors fall into three categories: protocol errors, tool execution errors, and v -Protocol errors are returned when the request violates the JSON-RPC or MCP specification (for example, malformed JSON, missing required fields, or unknown methods). +Protocol errors are returned as a JSON-RPC `error` object when the request can't be processed as an MCP request. They have two kinds of cause: the `Mcp-Session-Id` header, and an unsupported method. + +**Session errors** are returned before any tool runs. Common causes: + + * The `Mcp-Session-Id` header is missing: HTTP 400. + + * The identifier is malformed (not a UUID v4 or JWT): HTTP 400. + + * The server did not issue the identifier: HTTP 404. + + * The identifier has expired: HTTP 404. + + + + +A missing `Mcp-Session-Id` returns HTTP 400: @@ -807 +817,0 @@ Protocol errors are returned when the request violates the JSON-RPC or MCP speci - "id": 10, @@ -809,4 +819,4 @@ Protocol errors are returned when the request violates the JSON-RPC or MCP speci - "code": -32602, - "message": "Invalid params", - "data": { - "details": "Missing required field: queries" + "code": -32600, + "message": "Bad Request: mcp-session-id header is required" + }, + "id": null @@ -813,0 +824,24 @@ Protocol errors are returned when the request violates the JSON-RPC or MCP speci + +An unknown or expired identifier returns HTTP 404: + + + { + "jsonrpc": "2.0", + "error": { + "code": -99999, + "message": "Bad Request: Invalid or expired session ID" + }, + "id": null + } + +To resolve a session error, call `initialize` again and retry the request with the new `Mcp-Session-Id`. + +**Unsupported methods** return HTTP 200 with a JSON-RPC `error` object. The following example shows an unknown method. + + + { + "jsonrpc": "2.0", + "id": 10, + "error": { + "code": -32601, + "message": "Method not found" @@ -817 +851 @@ Protocol errors are returned when the request violates the JSON-RPC or MCP speci -### Tool execution errors +### Input validation errors @@ -819 +853,3 @@ Protocol errors are returned when the request violates the JSON-RPC or MCP speci -Tool execution errors are returned when a tool invocation fails at runtime (for example, rate limiting, invalid solution IDs, or upstream service errors). Tool errors are reported within the result object, not as MCP protocol-level errors, so the AI assistant can see and handle the error. +Input validation errors are returned when the arguments of a tool call fail schema validation (for example, a missing required field, an invalid value, or exceeding a maximum array length). An unknown tool name is returned the same way. These are tool errors, not protocol errors: the response has `isError: true` and the text starts with `MCP error -32602: Input validation error`, followed by one entry for each failing field. Each entry includes the `path` of the field, and for enum values, the allowed `options`. + +The following example shows a call to `search_aws_marketplace_solutions` without the required `queries` field. @@ -829 +865 @@ Tool execution errors are returned when a tool invocation fails at runtime (for - "text": "Failed to search listings: Rate limit exceeded" + "text": "MCP error -32602: Input validation error: Invalid arguments for tool search_aws_marketplace_solutions: [ { \"code\": \"invalid_type\", \"expected\": \"array\", \"received\": \"undefined\", \"path\": [\"queries\"], \"message\": \"Required\" } ]" @@ -836 +872,3 @@ Tool execution errors are returned when a tool invocation fails at runtime (for -### Validation errors +### Tool execution errors + +Tool execution errors are returned when a tool invocation fails at runtime (for example, rate limiting, invalid solution IDs, or upstream service errors). Tool errors are reported within the result object, not as MCP protocol-level errors, so the AI assistant can see and handle the error. @@ -838 +876,23 @@ Tool execution errors are returned when a tool invocation fails at runtime (for -Validation errors are returned when input fails schema validation (for example, invalid solution ID format, exceeding max array length, or missing required fields). These are surfaced as tool execution errors with `isError: true`. +The following example shows a call to `get_aws_marketplace_solution` with a solution ID that doesn't exist. + + + { + "jsonrpc": "2.0", + "id": 12, + "result": { + "content": [ + { + "type": "text", + "text": "{\"error\":{\"type\":\"ValidationException\",\"message\":\"Solution not found: prodview-doesnotexist\",\"code\":\"INVALID_FIELD_VALUE\"}}" + } + ], + "structuredContent": { + "error": { + "type": "ValidationException", + "message": "Solution not found: prodview-doesnotexist", + "code": "INVALID_FIELD_VALUE" + } + }, + "isError": true + } + }