AWS quick documentation change
Summary
Updated MCP integration documentation to add VPC connection support, clarify OAuth requirements for private servers, add troubleshooting section, and update limitations.
Security assessment
The changes add security documentation about OAuth endpoint requirements (must be publicly accessible even for private servers), authentication flows, and Microsoft Entra ID configuration guidance. However, there is no evidence of addressing a specific security vulnerability; the changes focus on feature enhancements and documentation improvements.
Diff
diff --git a/quick/latest/userguide/mcp-integration.md b/quick/latest/userguide/mcp-integration.md index 8a6659fc2..08bc5dbe6 100644 --- a//quick/latest/userguide/mcp-integration.md +++ b//quick/latest/userguide/mcp-integration.md @@ -7 +7 @@ -What you can doBefore you beginPrepare MCP server setup and authenticationSet up MCP integrationReview integrationManage MCP integrationsLimitations +Supported capabilitiesBefore you beginPrepare MCP server setup and authenticationSet up MCP integrationReview integrationManage MCP integrationsTroubleshootingLimitations @@ -15 +15,7 @@ With MCP integration in Amazon Quick, you can connect to remote MCP servers so t -## What you can do +You can connect to MCP servers that are reachable over the public internet. You can also connect to private MCP servers that are reachable from a virtual private cloud (VPC) in your AWS account by using a Amazon Quick VPC connection. The MCP server can be in the VPC, in another VPC reachable through peering or transit gateway, or on-premises reachable through AWS Direct Connect or VPN. For information about creating a VPC connection in Amazon Quick, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + +###### Important + +When you connect to a private MCP server through a VPC connection, the OAuth endpoints used by the MCP server must be reachable over the public internet. This applies to both user authentication (the authorization and token endpoints) and service authentication (the token endpoint). Private OAuth providers are not supported. MCP servers that do not require authentication are also supported. + +## Supported capabilities @@ -22 +28 @@ MCP integration registers MCP server tools as actions in Amazon Quick. -Each tool that is exposed by an MCP server is registered as an action that your AI assistant can invoke during conversations. The integration secures these connections by using Proof Key for Code Exchange (PKCE) with the S256 challenge method and Resource Indicators (RFC 8707) to bind access tokens to specific MCP servers. +Each tool that an MCP server exposes registers as an action that your AI assistant can invoke during conversations. The integration secures these connections by using Proof Key for Code Exchange (PKCE) with the S256 challenge method and Resource Indicators (RFC 8707) to bind access tokens to specific MCP servers. @@ -33,0 +40,2 @@ Before you set up MCP integration, make sure that you have the following: + * If you are connecting to a private MCP server, an active Amazon Quick VPC connection that has network access to the MCP server. For more information, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + @@ -39 +47 @@ Before you set up MCP integration, make sure that you have the following: -MCP integration supports remote servers only. HTTP streaming is preferred over Server-Sent Events (SSE). Local stdio connections and VPC connectivity are not supported. +MCP integration supports remote servers only. HTTP streaming is preferred over Server-Sent Events (SSE). Local stdio connections are not supported. @@ -43 +51 @@ MCP integration supports remote servers only. HTTP streaming is preferred over S -When you connect to an MCP server, Amazon Quick uses OAuth 2.0 Protected Resource Metadata (RFC 9728) to automatically discover authorization server information. The client sends an initial unauthenticated request to the MCP server. If the server responds with a 401 status that contains a `WWW-Authenticate` header with a `resource_metadata` URL, then Amazon Quick uses that URL to fetch the metadata document. If the header is not present, Amazon Quick falls back to the well-known URI at the server root. +When you connect to an MCP server, Amazon Quick uses OAuth 2.0 Protected Resource Metadata (RFC 9728) to automatically discover authorization server information. The client sends an initial unauthenticated request to the MCP server. If the server responds with a 401 status that contains a `WWW-Authenticate` header with a `resource_metadata` URL, then Amazon Quick uses that URL to fetch the metadata document. If the header is not present, then Amazon Quick falls back to the well-known URI at the server root. @@ -45 +53 @@ When you connect to an MCP server, Amazon Quick uses OAuth 2.0 Protected Resourc -If the authorization server supports Dynamic Client Registration (DCR), Amazon Quick automatically registers itself by using the discovered `registration_endpoint` from the authorization server metadata. No manual credential configuration is required. Both confidential and public client flows are supported. DCR applies regardless of the authentication method that you choose. +If the authorization server supports Dynamic Client Registration (DCR), then Amazon Quick automatically registers itself by using the discovered `registration_endpoint` from the authorization server metadata. No manual credential configuration is required. Amazon Quick supports both confidential and public client flows. DCR applies regardless of the authentication method that you choose. @@ -47 +55 @@ If the authorization server supports Dynamic Client Registration (DCR), Amazon Q -If the authorization server does not support DCR, you must manually provide credentials. Choose the authentication method that matches your MCP server requirements. +If the authorization server does not support DCR, then you must manually provide credentials. Choose the authentication method that matches your MCP server requirements. @@ -103,0 +112,6 @@ After you prepare your MCP server configuration and authentication credentials, + * **Connection type** – Choose how Amazon Quick connects to the MCP server: + + * **Public network** – Use this option for MCP servers that are reachable over the public internet. + + * A named VPC connection – Use this option for private MCP servers. The dropdown lists the VPC connections that are configured on your Amazon Quick account. Choose the connection that has network access to your MCP server. If you don't see your VPC connection in the list, confirm that it is fully provisioned and active. For more information, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + @@ -108 +122 @@ After you prepare your MCP server configuration and authentication credentials, - 7. Provide the appropriate configuration details. + 7. Enter the appropriate configuration details. @@ -121 +135 @@ After you prepare your MCP server configuration and authentication credentials, -After you create your MCP integration, the available tools are discovered and registered as actions. +After you create your MCP integration, Amazon Quick discovers the available tools and registers them as actions. @@ -138 +152 @@ After you configure authentication, review the MCP integration capabilities: -During the connection process that is described in Prepare MCP server setup and authentication, Amazon Quick also discovers and registers the tools that are available on the MCP server. After discovery completes, each tool is listed as an action that you can review and turn on. +During the connection process that is described in Prepare MCP server setup and authentication, Amazon Quick also discovers and registers the tools that the MCP server provides. After discovery completes, each tool is listed as an action that you can review and turn on. @@ -143,0 +158,71 @@ To edit, share, or delete your integration, see [Managing existing integrations] +## Troubleshooting + +Use the following guidance to diagnose and resolve common issues when you create or use an MCP integration in Amazon Quick. + +### Connector creation issues + + * **Connector passes discovery but fails at publish with`Creation failed`** – This error usually means that one or more tool definitions in your MCP server's `tools/list` response contain an invalid `inputSchema`. Amazon Quick validates each tool's `inputSchema` against JSON Schema Draft 7 or later during the publish phase. + +The most common cause is the deprecated Draft 3 syntax, where `required` is a boolean inside a property definition (for example, `"required": true`). In JSON Schema Draft 7 and later, `required` must be an array of property names at the schema root, as a sibling of `properties`. + +Update your tool definitions to use the correct format and redeploy your MCP server. After you redeploy, delete the failed connector and create a new one to retrigger discovery and publish. + +The following example shows the incorrect Draft 3 syntax: + + { + "type": "object", + "properties": { + "logNumber": { + "type": "string", + "description": "The permit log number", + "required": true + } + } + } + +The following example shows the correct Draft 7 syntax: + + { + "type": "object", + "properties": { + "logNumber": { + "type": "string", + "description": "The permit log number" + } + }, + "required": ["logNumber"] + } + +Some MCP framework libraries and code generators emit Draft 3 syntax by default. Check your framework documentation for the option that selects the JSON Schema output version. You can also validate your schemas with any JSON Schema Draft 7 validator before you deploy. For more information about `inputSchema` requirements, see [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) in the Model Context Protocol specification. + +You might also notice that connector creation hangs for two to five minutes before it fails. The elapsed time reflects internal retries during the publish phase, not a network timeout. The fix is the same: check your tool `inputSchema` definitions for JSON Schema Draft 7 compliance. + + + + +### VPC connection issues + + * **VPC connection is not listed in the**Connection type** dropdown, or MCP creation fails immediately after you select it** – The VPC connection might appear in the dropdown before provisioning is complete. Wait until the VPC connection shows as available on the Amazon Quick admin page before you create an MCP integration against it. For more information, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + + * **MCP creation fails because the MCP server hostname cannot be resolved** – Amazon Quick does not use the default VPC DNS resolver for MCP integrations. You must populate the **DNS resolver endpoints** field on the VPC connection with Route 53 Resolver inbound endpoint IP addresses that can resolve your MCP server hostname. This requirement applies to both private hostnames and to public hostnames that you want to resolve to a private address from within the VPC, such as endpoints fronted by AWS PrivateLink or a Route 53 private hosted zone. Without these resolver endpoints, the MCP server hostname cannot be resolved and integration creation fails. For more information, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + + * **MCP server is unreachable from the VPC connection** – Traffic from Amazon Quick to your MCP server originates from the subnets that you selected during VPC connection setup. Confirm that route tables, network ACLs, and security groups allow traffic between those subnets and the MCP server endpoint. For general VPC networking guidance, see [Configuring VPC connections in Amazon Quick Sight](./working-with-aws-vpc.html). + + * **Authentication fails when you use a private MCP server** – When you connect to a private MCP server through a VPC connection, the OAuth endpoints used by the MCP server must still be reachable over the public internet. This applies to both user authentication (authorization and token endpoints) and service authentication (token endpoint). Private OAuth providers are not supported. Confirm that the OAuth URLs that your MCP server returns in its protected resource metadata resolve over the public internet. + + + + +### Microsoft Entra ID issues + +If your MCP server uses Microsoft Entra ID as the authorization server, the following errors are common during connector setup. These issues apply to both public network connections and private MCP servers that you reach through a VPC connection. + + * **`AADSTS9010010` – the v2.0 endpoint rejects the resource parameter** – Amazon Quick sends a `resource` parameter on OAuth requests as required by the MCP specification (RFC 8707). The Entra ID v2.0 endpoint rejects requests that include both a `resource` parameter and `scope` values. To resolve this error, configure your app registration to use the Entra ID v1.0 OAuth endpoints and set `accessTokenAcceptedVersion` to `2` in the app manifest. + + * **`AADSTS90009` – application requests a token for itself** – When you use user authentication (authorization code flow) and the OAuth client and the MCP resource resolve to the same Entra ID application, Entra ID blocks the request. Create two separate app registrations: one client app for Amazon Quick and one resource app for the MCP server. This issue does not affect service authentication (client credentials flow), where a single app registration works. + + + + +If you encounter an issue that is not covered in the preceding sections, contact AWS Support through the Amazon Quick console or AWS Support Center. + @@ -149,0 +235,2 @@ When you use MCP integrations in Amazon Quick, be aware of the following limitat + * For MCP servers that you reach through a VPC connection, the OAuth endpoints used by the MCP server must be reachable over the public internet. This applies to both user authentication and service authentication. Private OAuth providers are not supported. + @@ -158 +245 @@ When you use MCP integrations in Amazon Quick, be aware of the following limitat - * Step-up authorization is not supported. If an MCP server requires additional scopes after the initial authorization (HTTP 403 with `insufficient_scope`), you must re-authorize the entire connection. Incremental permission upgrades are not available. + * Step-up authorization is not supported. If an MCP server requires additional scopes after the initial authorization (HTTP 403 with `insufficient_scope`), then you must re-authorize the entire connection. Incremental permission upgrades are not available. @@ -162 +249 @@ When you use MCP integrations in Amazon Quick, be aware of the following limitat - * Amazon Quick does not extract the `scope` parameter from the server's initial 401 `WWW-Authenticate` challenge. Scopes are determined from the Protected Resource Metadata document instead. + * Amazon Quick does not extract the `scope` parameter from the server's initial 401 `WWW-Authenticate` challenge. Amazon Quick determines scopes from the Protected Resource Metadata document instead.