AWS Bedrock KB Retrieval

Servidor MCP de Recuperação de Knowledge Base da Amazon Bedrock

Servidor MCP para acessar Knowledge Bases da Amazon Bedrock

Recursos

Descubra knowledge bases e suas fontes de dados

• Encontre e explore todas as knowledge bases disponíveis
• Pesquise knowledge bases por nome ou tag
• Liste as fontes de dados associadas a cada knowledge base

Consulte knowledge bases com linguagem natural

• Recupere informações usando consultas conversacionais
• Obtenha passagens relevantes das suas knowledge bases
• Acesse informações de citação para todos os resultados

Filtre resultados por fonte de dados

• Foque suas consultas em fontes de dados específicas
• Inclua ou exclua fontes de dados específicas
• Priorize resultados de fontes de dados específicas

Recuperação agentiva em knowledge bases gerenciadas

• Planeje uma estratégia de recuperação em várias etapas e sintetize uma resposta citada
• Pesquise várias knowledge bases em uma única chamada
• Trace condensado opcional do planejamento e das etapas de recuperação do agente
• Apenas knowledge bases gerenciadas; a ferramenta rejeita outros tipos com uma mensagem clara

Alcance conteúdo protegido por ACL

• Passe user_id para recuperar conteúdo de fontes de dados com reconhecimento de ACL (SharePoint, OneDrive, Confluence com ACLs por documento)
• Sem isso, esse conteúdo fica inacessível, e a etapa de expansão de documento completo da recuperação agentiva falha com "UserContext é obrigatório para fontes de dados com reconhecimento de ACL"
• Os resultados são filtrados para o que esse usuário está autorizado a ver

Suporte a knowledge bases gerenciadas e vetoriais

• Funciona com knowledge bases vetoriais (type: VECTOR) e knowledge bases gerenciadas (type: MANAGED)
• O tipo de knowledge base é detectado automaticamente e a configuração correta de Retrieve é enviada (vectorSearchConfiguration ou managedSearchConfiguration)
• A filtragem por fonte de dados usa a chave de metadados apropriada para o tipo de knowledge base
• A ferramenta ListKnowledgeBases relata o type de cada knowledge base

Reordene resultados

• Melhore a relevância dos resultados de recuperação
• Use os recursos de reordenação do Amazon Bedrock
• Ordene os resultados por relevância para sua consulta

Pré-requisitos

Requisitos de instalação

1. Instale uv do Astral ou do README do GitHub
2. Instale Python usando uv python install 3.10

Requisitos da AWS

1. Configuração da AWS CLI: Você deve ter a AWS CLI configurada com credenciais e um AWS_PROFILE que tenha acesso ao Amazon Bedrock e às Knowledge Bases
2. Knowledge Base do Amazon Bedrock: Você deve ter pelo menos uma Knowledge Base do Amazon Bedrock com a tag mcp-multirag-kb com um valor de true
3. Permissões do IAM: Sua função/usuário do IAM deve ter permissões apropriadas para:
   • Listar e descrever knowledge bases
   • Acessar fontes de dados
   • Consultar knowledge bases

Requisitos de reordenação

Se você pretende usar a funcionalidade de reordenação, sua Knowledge Base do Bedrock precisa de permissões adicionais:

1. Sua função do IAM deve ter permissões para as ações bedrock:Rerank e bedrock:InvokeModel
2. A função de serviço do Amazon Bedrock Knowledge Bases também deve ter essas permissões
3. A disponibilidade de reordenação difere por modelo: amazon.rerank-v1:0 não é oferecido em us-east-1, enquanto cohere.rerank-v3-5:0 é. O servidor valida o par (região, modelo) e falha rapidamente com uma mensagem clara. Consulte a documentação oficial para obter uma lista atualizada de regiões suportadas.
4. Habilite o acesso ao modelo para os modelos de reordenação disponíveis na região especificada.

Requisitos de recuperação agentiva

A ferramenta AgenticQueryKnowledgeBases chama AgenticRetrieveStream, que é suportada para apenas knowledge bases gerenciadas (type: MANAGED). Ela planeja uma estratégia de recuperação e, a menos que você passe generate_response=false, invoca um modelo de fundação para escrever uma resposta citada.

1. Sua função do IAM precisa de bedrock:AgenticRetrieveStream na knowledge base, além das permissões listadas acima
2. Como ela invoca um modelo de fundação, custa materialmente mais por chamada do que QueryKnowledgeBases. Passe generate_response=false para recuperação sem síntese
3. RetrieveAndGenerate não é suportado para knowledge bases gerenciadas, então recuperação agentiva com generate_response=true é a maneira de obter uma resposta gerada a partir de uma

Controlando a reordenação

A reordenação pode ser habilitada ou desabilitada globalmente usando a variável de ambiente BEDROCK_KB_RERANKING_ENABLED:

• Defina como false (padrão): Desabilita a reordenação para todas as consultas, a menos que seja explicitamente habilitada
• Defina como true: Habilita a reordenação para todas as consultas, a menos que seja explicitamente desabilitada

A variável de ambiente aceita vários formatos:

• Para habilitar: 'true', '1', 'yes' ou 'on' (sem diferenciar maiúsculas de minúsculas)
• Para desabilitar: qualquer outro valor ou não definido (comportamento padrão)

Esta configuração fornece um padrão global, enquanto chamadas individuais de API ainda podem substituí-la definindo explicitamente o parâmetro reranking.

Para instruções detalhadas sobre como configurar knowledge bases, consulte:

• Criar uma knowledge base
• Gerenciando permissões para knowledge bases do Amazon Bedrock
• Permissões para reordenação no Amazon Bedrock

Instalação

Kiro	Cursor	VS Code

Configure o servidor MCP na configuração do seu cliente MCP (por exemplo, para Kiro, edite ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
        "BEDROCK_KB_RERANKING_ENABLED": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Instalação no Windows

Para usuários do Windows, o formato de configuração do servidor MCP é ligeiramente diferente:

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.bedrock-kb-retrieval-mcp-server@latest",
        "awslabs.bedrock-kb-retrieval-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

ou docker após um docker build -t awslabs/bedrock-kb-retrieval-mcp-server . bem-sucedido:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

  {
    "mcpServers": {
      "awslabs.bedrock-kb-retrieval-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "--env",
          "FASTMCP_LOG_LEVEL=ERROR",
          "--env",
          "KB_INCLUSION_TAG_KEY=optional-tag-key-to-filter-kbs",
          "--env",
          "BEDROCK_KB_RERANKING_ENABLED=false",
          "--env",
          "AWS_REGION=us-east-1",
          "--env-file",
          "/full/path/to/file/above/.env",
          "awslabs/bedrock-kb-retrieval-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

NOTA: Suas credenciais precisarão ser mantidas atualizadas a partir do seu host

Limitações

• Resultados com tipo de conteúdo IMAGE não são incluídos na resposta da consulta da KB.
• O parâmetro reranking requer permissões adicionais, acesso ao modelo do Amazon Bedrock e está disponível apenas em regiões específicas.