Integração do Model Context Protocol (MCP)

Um endpoint de servidor MCP com acesso apropriado.

Credenciais de autenticação para o servidor MCP, se necessário. Para obter mais informações, consulte Preparar a configuração e a autenticação do servidor MCP.

Uma assinatura do Amazon Quick Enterprise.

Se você estiver se conectando a um servidor MCP privado, uma conexão Amazon Quick VPC ativa que tenha acesso de rede ao servidor MCP. Para obter mais informações, consulte Configurando conexões VPC no Amazon Quick Sight.

O conector passa na descoberta, mas falha na publicação com Creation failed — Esse erro geralmente significa que uma ou mais definições de ferramentas na tools/list resposta do seu servidor MCP contêm uma mensagem inputSchema inválida. O Amazon Quick valida cada ferramenta em inputSchema relação ao JSON Schema Draft 7 ou posterior durante a fase de publicação.

A causa mais comum é a sintaxe obsoleta do Draft 3, em que required há um booleano dentro de uma definição de propriedade (por exemplo,). "required": true No JSON Schema Draft 7 e versões posteriores, required deve haver uma matriz de nomes de propriedades na raiz do esquema, como um irmão de. properties

Atualize suas definições de ferramentas para usar o formato correto e reimplante seu servidor MCP. Depois de reimplantar, exclua o conector com falha e crie um novo para reativar a descoberta e a publicação.

O exemplo a seguir mostra a sintaxe incorreta do Rascunho 3:

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number",
      "required": true
    }
  }
}

O exemplo a seguir mostra a sintaxe correta do Draft 7:

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number"
    }
  },
  "required": ["logNumber"]
}

Algumas bibliotecas da estrutura MCP e geradores de código emitem a sintaxe do Draft 3 por padrão. Verifique a documentação da estrutura para ver a opção que seleciona a versão de saída do esquema JSON. Você também pode validar seus esquemas com qualquer validador JSON Schema Draft 7 antes da implantação. Para obter mais informações sobre inputSchema requisitos, consulte Ferramentas na especificação do Model Context Protocol.

Você também pode notar que a criação do conector é interrompida por dois a cinco minutos antes de falhar. O tempo decorrido reflete as novas tentativas internas durante a fase de publicação, não o tempo limite da rede. A correção é a mesma: verifique se inputSchema as definições da ferramenta estão em conformidade com o JSON Schema Draft 7.

A conexão VPC não está listada na lista suspensa Tipo de conexão, ou a criação da MCP falha imediatamente após você selecioná-la — a conexão VPC pode aparecer na lista suspensa antes que o provisionamento seja concluído. Espere até que a conexão VPC apareça como disponível na página de administração do Amazon Quick antes de criar uma integração MCP com ela. Para obter mais informações, consulte Configurando conexões VPC no Amazon Quick Sight.

A criação do MCP falha porque o nome do host do servidor MCP não pode ser resolvido — o Amazon Quick não usa o resolvedor de DNS VPC padrão para integrações de MCP. Você deve preencher o campo de endpoints do resolvedor de DNS na conexão VPC com os endereços IP do endpoint de entrada do Resolvedor do Route 53 que possam resolver o nome de host do servidor MCP. Esse requisito se aplica tanto aos nomes de host privados quanto aos nomes de host públicos que você deseja resolver para um endereço privado de dentro da VPC, como endpoints fronteirizados ou uma zona hospedada privada do AWS PrivateLink Route 53. Sem esses endpoints do resolvedor, o nome do host do servidor MCP não pode ser resolvido e a criação da integração falha. Para obter mais informações, consulte Configurando conexões VPC no Amazon Quick Sight.

O servidor MCP está inacessível a partir da conexão VPC — O tráfego do Amazon Quick para seu servidor MCP tem origem nas sub-redes que você selecionou durante a configuração da conexão VPC. Confirme se as tabelas de rotas, as ACLs de rede e os grupos de segurança permitem o tráfego entre essas sub-redes e o endpoint do servidor MCP. Para obter orientações gerais sobre redes VPC, consulte. Configurando conexões VPC no Amazon Quick Sight

A autenticação falha quando você usa um servidor MCP privado — Quando você se conecta a um servidor MCP privado por meio de uma conexão VPC, os endpoints OAuth usados pelo servidor MCP ainda devem estar acessíveis pela Internet pública. Isso se aplica tanto à autenticação do usuário (endpoints de autorização e token) quanto à autenticação de serviço (endpoint de token). Não há suporte para provedores privados de OAuth. Confirme se os URLs do OAuth que seu servidor MCP retorna em seus metadados de recursos protegidos são resolvidos pela Internet pública.

AADSTS9010010— o endpoint v2.0 rejeita o parâmetro do recurso — o Amazon Quick envia um resource parâmetro nas solicitações do OAuth conforme exigido pela especificação MCP (RFC 8707). O endpoint Entra ID v2.0 rejeita solicitações que incluem um resource parâmetro e valores. scope Para resolver esse erro, configure o registro do seu aplicativo para usar os endpoints do Entra ID v1.0 OAuth e defina-os 2 no accessTokenAcceptedVersion manifesto do aplicativo.

AADSTS90009— o aplicativo solicita um token para si mesmo — Quando você usa a autenticação do usuário (fluxo de código de autorização) e o cliente OAuth e o recurso MCP resolvem para o mesmo aplicativo Entra ID, o Entra ID bloqueia a solicitação. Crie dois registros de aplicativos separados: um aplicativo cliente para o Amazon Quick e um aplicativo de recursos para o servidor MCP. Esse problema não afeta a autenticação do serviço (fluxo de credenciais do cliente), em que um único registro de aplicativo funciona.

As operações de MCP têm um tempo limite fixo de 60 segundos. As operações que excedem esse limite falham automaticamente com um erro HTTP 424.

Para servidores MCP que você acessa por meio de uma conexão VPC, os endpoints OAuth usados pelo servidor MCP devem estar acessíveis pela Internet pública. Isso se aplica tanto à autenticação do usuário quanto à autenticação do serviço. Não há suporte para provedores privados de OAuth.

Os cabeçalhos HTTP personalizados não são suportados nas operações do MCP. Somente cabeçalhos padrão do sistema são transmitidos.

As listas de ferramentas permanecem estáticas após o registro inicial. Para obter as alterações nas ferramentas do lado do servidor, você deve excluir a integração e recriá-la.

A criação do conector pode falhar se o URI de callback do Amazon Quick não estiver na lista de permissões de provedores terceirizados.

Problemas de conectividade do servidor resultam em falha imediata sem novas tentativas.

Step-up a autorização não é suportada. Se um servidor MCP exigir escopos adicionais após a autorização inicial (HTTP 403 cominsufficient_scope), você deverá reautorizar toda a conexão. As atualizações incrementais de permissões não estão disponíveis.

O tratamento do escopo tem as seguintes limitações:

Somente o Registro Dinâmico de Cliente (DCR) é suportado para o registro automático de clientes. Documentos de metadados de ID de cliente não são suportados.

Well-known A descoberta de URI usa somente o caminho raiz do servidor. Path-specific localizações de metadados (descoberta de inserção de caminhos) não são suportadas. Essa limitação pode impedir a descoberta de servidores que veiculam metadados somente em URIs específicos do caminho.