Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # OpenSearch Server MCP [OpenSearch MCP server](https://github.com/opensearch-project/opensearch-mcp-server-py) [(`opensearch-mcp-server-py`) è un'implementazione open source del Model Context Protocol per.](https://modelcontextprotocol.io) OpenSearch Presenta OpenSearch APIs come strumenti che gli assistenti di intelligenza artificiale e i framework di agenti possono chiamare direttamente, così puoi porre domande come *«Quali indici* esistono nel mio cluster?» oppure *«Mostrami le query più lente dell'ultima ora» e l'*agente gestirà le chiamate API per tuo conto. Il server funziona sia con domini di OpenSearch servizio gestiti che con raccolte Serverless. OpenSearch Puoi collegarlo alla programmazione IDEs (Kiro, Claude Code, Cursor), agli assistenti AI desktop (Claude Desktop) e ai framework di agenti (Strands Agents,). LangGraph ## Prerequisiti + Python 3.10 o successivo. + [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)(consigliato) o. `pip` + Un OpenSearch endpoint raggiungibile: un dominio di OpenSearch servizio, una raccolta OpenSearch Serverless o un cluster autogestito. OpenSearch + Credenziali con autorizzazione alla chiamata che desideri esporre. OpenSearch APIs Per le politiche IAM sui domini OpenSearch di servizio, vedi. [Policy basate sull’identità](ac.md#ac-types-identity) Per le politiche di accesso ai dati OpenSearch serverless, consulta. [Controllo dell'accesso ai dati per Amazon OpenSearch Serverless](serverless-data-access.md) ## Installa Esegui il server con `uvx` (non è richiesta alcuna installazione) o installalo localmente: ``` # Run directly with uvx (recommended – no install step) uvx opensearch-mcp-server-py # Or install with pip pip install opensearch-mcp-server-py ``` La maggior parte degli utenti configura il proprio assistente IDE o AI per avviare automaticamente il server. Vedi [Configura in un IDE di codifica](mcp-server-configure-ide.md) e [Da utilizzare con i framework degli agenti](mcp-server-configure-frameworks.md) per alcuni esempi. ## Autenticazione Configura l'autenticazione tramite variabili di ambiente (modalità a cluster singolo) o per cluster in un file di configurazione YAML (modalità multicluster). Il server applica i metodi di autenticazione nel seguente ordine di priorità: no-auth, header-based, ruolo IAM, autenticazione di base, chiavi di accesso. AWS **Ruolo IAM (SigV4): consigliato per i domini di servizio OpenSearch ** ``` export OPENSEARCH_URL="{{https://your-domain-endpoint}}" export AWS_IAM_ARN="arn:aws:iam::{{123456789012}}:role/{{YourOpenSearchRole}}" export AWS_REGION="{{us-east-1}}" ``` Il ruolo deve disporre dell'autorizzazione per chiamare gli utenti utilizzati OpenSearch APIs dal server. Vedi [Altre policy di esempio](ac.md#ac-samples) per esempi di policy. **AWS credenziali o profilo** ``` export OPENSEARCH_URL="{{https://your-domain-endpoint}}" export AWS_REGION="{{us-east-1}}" export AWS_PROFILE="{{your-aws-profile}}" ``` **OpenSearch raccolte serverless** Imposta `AWS_OPENSEARCH_SERVERLESS=true` in modo che il server firmi le richieste con il nome del `aoss` `es` servizio anziché. Assicurati che al principale sia concesso l'accesso tramite una politica di accesso ai dati sulla raccolta (vedi[Controllo dell'accesso ai dati per Amazon OpenSearch Serverless](serverless-data-access.md)). ``` 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}}" ``` **Autenticazione Base** ``` export OPENSEARCH_URL="{{https://your-domain-endpoint}}" export OPENSEARCH_USERNAME="{{username}}" export OPENSEARCH_PASSWORD="{{password}}" ``` Non incorporate password nei file di configurazione che potrebbero essere archiviati nel controllo del codice sorgente. Usa il gestore segreto o l'ambiente shell del tuo sistema operativo per fornire le credenziali. ## Considerazioni relative alla sicurezza Il server MCP viene eseguito con le credenziali fornite dall'utente. Qualsiasi cosa queste credenziali siano autorizzate a fare, l'assistente AI può potenzialmente attivarla per tuo conto. Segui queste pratiche: + **Utilizza credenziali con privilegi minimi.** Crea un ruolo IAM dedicato o un OpenSearch utente limitato agli indici e alle azioni di cui l'agente ha bisogno. Evita di riutilizzare le credenziali di amministratore. + **Sviluppo e produzione separati.** Indirizza il server verso i cluster non di produzione per l'esplorazione. Utilizza la modalità multipla con nomi di cluster espliciti quando è richiesto l'accesso alla produzione. + **Strumenti di filtro.** Disattiva le categorie di strumenti non necessarie al tuo flusso di lavoro. Imposta `OPENSEARCH_DISABLED_CATEGORIES=core_tools` per disabilitare il set predefinito o usa `OPENSEARCH_ENABLED_CATEGORIES` per abilitare solo categorie specifiche. + **Proteggi le credenziali.** Preferisci AWS i profili e i ruoli IAM alle chiavi di accesso statiche. Non inserire mai segreti nei file di configurazione nel controllo del codice sorgente. + **Rivedi l'output dello strumento.** Le risposte dello strumento MCP vengono restituite al modello linguistico come contesto. Evita di eseguire il server su indici che contengono dati sensibili che non desideri vengano esposti al tuo provider di intelligenza artificiale. ## Risoluzione dei problemi **L'assistente non vede nessuno strumento OpenSearch ** Conferma che il file di configurazione è JSON valido e riavvia completamente il client. La maggior parte dei client carica i server MCP solo all'avvio. **Le chiamate agli strumenti restituiscono 403 Forbidden** Le tue credenziali non dispongono dell'autorizzazione per l'API che lo strumento sta chiamando. Per i domini OpenSearch di servizio, consulta la politica di accesso al dominio e le politiche IAM associate al tuo ruolo. Per OpenSearch Serverless, consulta la politica di accesso ai dati della raccolta. **Errori di mancata corrispondenza delle firme con Serverless OpenSearch ** Assicurati che `AWS_OPENSEARCH_SERVERLESS=true` sia impostato (o `is_serverless: true` in modalità multipla). Senza di essa, il server firma con il nome del `es` servizio anziché`aoss`. **Lo strumento di cui hai bisogno non è disponibile** Controlla se si trova in una categoria non predefinita e `OPENSEARCH_ENABLED_CATEGORIES` abilitalo con o `enabled_categories` nella tua configurazione YAML. [Per ulteriore assistenza, apri un problema nell'archivio. opensearch-mcp-server-py ](https://github.com/opensearch-project/opensearch-mcp-server-py/issues) ## Risorse aggiuntive + [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py)su GitHub : fonte, problemi e note di rilascio. + [Guida per l'utente](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md): riferimento completo alla configurazione, inclusi i trasporti in streaming e l'implementazione di Kubernetes. + [Strands Agents: SDK per agenti](https://strandsagents.com) AWS nativi con supporto MCP integrato. + [LangGraph](https://github.com/langchain-ai/langgraph)— Framework di orchestrazione di basso livello per agenti stateful. + [OpenSearch Competenze degli agenti](opensearch-agent-skills.md)— La raccolta di competenze complementari per flussi di lavoro incentrati sulle attività.