View a markdown version of this page

OpenSearch Servidor MCP - OpenSearch Serviço Amazon
Pré-requisitosInstalarAutenticaçãoConsiderações sobre segurançaSolução de problemasRecursos adicionais do

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

OpenSearch Servidor MCP

OpenSearch O servidor MCP (opensearch-mcp-server-py) é uma implementação de código aberto do Model Context Protocol for OpenSearch. Ele expõe OpenSearch APIs como ferramentas que assistentes de IA e estruturas de agentes podem chamar diretamente, para que você possa fazer perguntas como “Quais índices existem no meu cluster?” ou “Mostre-me as consultas mais lentas da última hora” e o agente gerencia as chamadas de API em seu nome.

O servidor funciona com domínios de OpenSearch serviço gerenciados e coleções sem OpenSearch servidor. Você pode conectá-lo à codificação IDEs (Kiro, Claude Code, Cursor), assistentes de IA de desktop (Claude Desktop) e estruturas de agentes (Strands Agents). LangGraph

Pré-requisitos

  • Python 3.10 ou posterior.

  • uv(recomendado) oupip.

  • Um OpenSearch endpoint acessível: um domínio de OpenSearch serviço, uma coleção OpenSearch sem servidor ou um cluster autogerenciado. OpenSearch

  • Credenciais com permissão para ligar para o OpenSearch APIs que você deseja expor. Para políticas do IAM em domínios OpenSearch de serviço, consultePolíticas baseadas em identidade. Para políticas de acesso a dados OpenSearch sem servidor, consulte. Controle de acesso a dados para Amazon OpenSearch Serverless

Instalar

Execute o servidor com uvx (sem necessidade de instalação) ou instale-o localmente:

# Run directly with uvx (recommended – no install step)
uvx opensearch-mcp-server-py

# Or install with pip
pip install opensearch-mcp-server-py

A maioria dos usuários configura seu IDE ou assistente de IA para iniciar o servidor automaticamente. Veja Configurar em um IDE de codificação e Use com estruturas de agentes veja exemplos.

Autenticação

Configure a autenticação por meio de variáveis de ambiente (modo de cluster único) ou por cluster em um arquivo de configuração YAML (modo de vários clusters). O servidor aplica métodos de autenticação na seguinte ordem de prioridade: sem autenticação, baseado em cabeçalho, função do IAM, autenticação básica, chaves de acesso. AWS

Função do IAM (SigV4) — recomendada para OpenSearch domínios de serviço
export OPENSEARCH_URL="https://your-domain-endpoint"
export AWS_IAM_ARN="arn:aws:iam::123456789012:role/YourOpenSearchRole"
export AWS_REGION="us-east-1"

A função deve ter permissão para chamar o que OpenSearch APIs o servidor usa. Consulte Exemplos adicionais de políticas para ver exemplos de políticas.

AWS credenciais ou perfil
export OPENSEARCH_URL="https://your-domain-endpoint"
export AWS_REGION="us-east-1"
export AWS_PROFILE="your-aws-profile"
OpenSearch Coleções sem servidor

Defina AWS_OPENSEARCH_SERVERLESS=true para que o servidor assine solicitações com o nome do aoss serviço em vez dees. Certifique-se de que o principal tenha acesso por meio de uma política de acesso a dados na coleção (consulteControle de acesso a dados para Amazon OpenSearch Serverless).

export OPENSEARCH_URL="https://collection-id.us-east-1.aoss.amazonaws.com"
export AWS_OPENSEARCH_SERVERLESS="true"
export AWS_REGION="us-east-1"
export AWS_PROFILE="your-aws-profile"
Autenticação básica
export OPENSEARCH_URL="https://your-domain-endpoint"
export OPENSEARCH_USERNAME="username"
export OPENSEARCH_PASSWORD="password"
Importante

Não incorpore senhas em arquivos de configuração que possam ser verificados no controle de origem. Use o gerenciador secreto ou o ambiente shell do seu sistema operacional para fornecer credenciais.

Considerações sobre segurança

O servidor MCP é executado com as credenciais que você fornece. Qualquer coisa que essas credenciais estejam autorizadas a fazer, o assistente de IA pode potencialmente acionar em seu nome. Siga estas práticas:

  • Use credenciais com privilégios mínimos. Crie uma função do IAM dedicada ou um OpenSearch usuário com escopo de acordo com os índices e ações de que o agente precisa. Evite reutilizar as credenciais do administrador.

  • Desenvolvimento e produção separados. Aponte o servidor para clusters que não são de produção para exploração. Use o modo múltiplo com nomes de cluster explícitos quando o acesso à produção for necessário.

  • Ferramentas de filtro. Desative as categorias de ferramentas que seu fluxo de trabalho não precisa. OPENSEARCH_DISABLED_CATEGORIES=core_toolsDefina para desativar o conjunto padrão ou use OPENSEARCH_ENABLED_CATEGORIES para ativar somente categorias específicas.

  • Proteja as credenciais. Prefira AWS perfis e funções do IAM em vez de chaves de acesso estáticas. Nunca confirme segredos em arquivos de configuração no controle de origem.

  • Revise a saída da ferramenta. As respostas da ferramenta MCP são devolvidas ao modelo de linguagem como contexto. Evite executar o servidor em índices que contenham dados confidenciais que você não deseja que sejam expostos ao seu provedor de IA.

Solução de problemas

O assistente não vê nenhuma OpenSearch ferramenta

Confirme se seu arquivo de configuração é um JSON válido e reinicie totalmente o cliente. A maioria dos clientes só carrega servidores MCP na inicialização.

As chamadas da ferramenta retornam 403 Forbidden

Suas credenciais não têm permissão para a API que a ferramenta está chamando. Para domínios OpenSearch de serviço, revise a política de acesso ao domínio e as políticas do IAM anexadas à sua função. Para OpenSearch Serverless, revise a política de acesso a dados da coleção.

Erros de incompatibilidade de assinatura com OpenSearch Serverless

Verifique se AWS_OPENSEARCH_SERVERLESS=true está configurado (ou is_serverless: true no modo múltiplo). Sem isso, o servidor assina com o nome do es serviço em vez deaoss.

A ferramenta que você precisa não está disponível

Verifique se ele está em uma categoria não padrão e ative-o com OPENSEARCH_ENABLED_CATEGORIES ou enabled_categories na sua configuração YAML.

Para obter mais ajuda, abra um problema no opensearch-mcp-server-py repositório.

Recursos adicionais do

  • opensearch-mcp-server-pyativado GitHub — Fonte, edições e notas de lançamento.

  • Guia do usuário — Referência de configuração completa, incluindo transportes de streaming e implantação do Kubernetes.

  • Strands Agents AWS— SDK de agente nativo com suporte MCP integrado.

  • LangGraph— Estrutura de orquestração de baixo nível para agentes com estado.

  • OpenSearch Habilidades do agente— A coleção de habilidades complementares para fluxos de trabalho focados em tarefas.