# Servidor MCP para AWS Labs Aurora DSQL Um servidor de protocolo de contexto para modelos (MCP) do AWS Labs para Aurora DSQL ## Recursos + Converter perguntas e comandos legíveis por humanos em consultas SQL estruturadas compatíveis com o Postgres e executá-las no banco de dados Aurora DSQL configurado. + Somente leitura por padrão, transações habilitadas com `--allow-writes` + Reutilização de conexão entre solicitações para melhorar a performance + Acesso integrado à documentação, pesquisa e recomendações de práticas recomendadas do Aurora DSQL ## Ferramentas disponíveis ### Operações de banco de dados + **readonly\$1query**: execute consultas SQL somente leitura em seu cluster DSQL. + **transact**: execute operações de gravação em uma transação (requer `--allow-writes`). + **get\$1schema**: recupera informações do esquema da tabela. ### Documentação e recomendações + **dsql\$1search\$1documentation**: pesquise a documentação do Aurora DSQL. + Parâmetros: `search_phrase` (obrigatório), `limit` (opcional). + **dsql\$1read\$1documentation**: leia páginas específicas de documentação do DSQL. + Parâmetros: `url` (obrigatório), `start_index` (opcional), `max_length` (opcional). + **dsql\$1recommend**: receba recomendações sobre as práticas recomendadas do DSQL. + Parâmetros: `url` (obrigatórios) ## Pré-requisitos 1. Uma conta da AWS com um [cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html). 1. Esse servidor MCP só pode ser executado localmente no mesmo host que o seu cliente LLM. 1. Configurar credenciais da AWS com acesso aos serviços da AWS + Você precisa de uma conta da AWS com um perfil que inclua essas permissões: + `dsql:DbConnectAdmin`: conecte-se aos clusters do DSQL como usuário administrador. + `dsql:DbConnect`: conecte-se a clusters do DSQL com perfis de banco de dados personalizados (necessário somente se estiver usando usuários que não sejam administradores). + Configurar credenciais da AWS com `aws configure` ou variáveis de ambiente ## Instalação Para a maioria das ferramentas, atualizar a configuração seguindo as instruções [de instalação padrão](#default-installation) deve ser suficiente. Há instruções separadas para o [Claude Code](#claude-code) e o [Codex](#codex). ### Instalação padrão: atualizar o arquivo de configuração do MCP relevante #### Usar o `uv` 1. Instale `uv` por meio do [Astral](https://docs.astral.sh/uv/getting-started/installation/) ou do [LEIAME do GitHub](https://github.com/astral-sh/uv#installation). 1. Instale o Python usando `uv python install 3.10`. Configure o servidor MCP na configuração do seu cliente MCP ([Encontrar o arquivo de configuração do MCP](#finding-mcp-config-file)) ``` { "mcpServers": { "awslabs.aurora-dsql-mcp-server": { "command": "uvx", "args": [ "awslabs.aurora-dsql-mcp-server@latest", "--cluster_endpoint", "[your dsql cluster endpoint, e.g. abcdefghijklmnopqrst234567.dsql.us-east-1.on.aws]", "--region", "[your dsql cluster region, e.g. us-east-1]", "--database_user", "[your dsql username, e.g. admin]", "--profile", "[your aws profile, e.g. default]" ], "env": { "FASTMCP_LOG_LEVEL": "ERROR" }, "disabled": false, "autoApprove": [] } } } ``` #### Instalação do Windows Para usuários do Windows, o formato de configuração do servidor MCP é um pouco diferente: ``` { "mcpServers": { "awslabs.aurora-dsql-mcp-server": { "disabled": false, "timeout": 60, "type": "stdio", "command": "uv", "args": [ "tool", "run", "--from", "awslabs.aurora-dsql-mcp-server@latest", "awslabs.aurora-dsql-mcp-server.exe" ], "env": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_PROFILE": "your-aws-profile", "AWS_REGION": "us-east-1" } } } } ``` #### Localizar o arquivo de configuração do cliente do MCP Para algumas das ferramentas de desenvolvimento de agentes mais comuns, você pode encontrar as configurações do seu cliente do MCP nos seguintes caminhos de arquivo: + Kiro: + Configuração do usuário: `~/.kiro/settings/mcp.json` + Configuração do espaço de trabalho: `/path/to/workspace/.kiro/settings/mcp.json` + Claude Code: consulte [Instalação do Claude Code](#claude-code) para receber ajuda detalhada sobre a configuração. + Configuração do usuário: `~/.claude.json` em `"mcpServers"` + Configuração do projeto: `/path/to/project/.mcp.json` + Configuração local: `~/.claude.json` em `"projects" -> "path/to/project" -> "mcpServers"` + Cursor: + Global: `~/.cursor/mcp.json` + Projeto: `/path/to/project/.cursor/mcp.json` + Codex: `~/.codex/config.toml` + Cada servidor MCP é configurado com uma tabela `[mcp_servers.]` no arquivo de configuração. Consulte as [instruções de instalação do Custom Codex](#codex). + Warp: + Edição de arquivos: `~/.warp/mcp_settings.json` + Editor de aplicações: `Settings > AI > Manage MCP Servers` e cole o json. + CLI do Amazon Q Developer: `~/.aws/amazonq/mcp.json` + Cline: normalmente, um caminho aninhado do VS Code: `~/.vscode-server/path/to/cline_mcp_settings.json` ### Claude Code #### Pré-requisitos **Importante:** o gerenciamento do servidor MCP só está disponível por meio da experiência do terminal da CLI do Claude Code, não do modo de painel nativo do VS Code. Instale primeiro a CLI do Claude Code seguindo o [processo de instalação nativo recomendado](https://code.claude.com/docs/en/setup#native-install-recommended) do Claude. #### Escolher o escopo correto O Claude Code oferece três escopos diferentes: local (padrão), projeto e usuário, e detalha qual escopo escolher com base na sensibilidade da credencial e na necessidade de compartilhamento. Consulte a documentação do Claude Code sobre os [escopos de instalação do MCP](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) para receber mais detalhes. 1. Os servidores **com escopo local** representam o nível de configuração padrão e são armazenados em `~/.claude.json` no caminho do seu projeto. **Ambos** são privados para você e só podem ser acessados no diretório atual do projeto. Esse é o `scope` padrão ao criar servidores MCP. 1. Os servidores **com escopo de projeto** **permitem a colaboração em equipe** e, ao mesmo tempo, só podem ser acessados em um diretório de projetos. Servidores com escopo de projeto incluem um arquivo `.mcp.json` na raiz do seu projeto. Esse arquivo foi projetado para ser verificado no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços do MCP. Quando você adiciona um servidor com escopo de projeto, o Claude Code cria ou atualiza automaticamente esse arquivo com a estrutura de configuração apropriada. 1. Os servidores **com escopo de usuário** são armazenados em `~/.claude.json` e **oferecem acessibilidade entre projetos**. Eles os disponibilizam em todos os projetos em sua máquina, permanecendo **privados da sua conta de usuário**. #### Usar a CLI do Claude (recomendado) O uso de uma sessão de CLI `claude` interativa permite uma melhor experiência de solução de problemas, portanto, esse é o caminho recomendado. ``` claude mcp add amazon-aurora-dsql \ --scope [one of local, project, or user] \ --env FASTMCP_LOG_LEVEL="ERROR" \ -- uvx "awslabs.aurora-dsql-mcp-server@latest" \ --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \ --region "[dsql cluster region, eg. us-east-1]" \ --database_user "[your-username]" ``` ##### Solução de problemas: usar o Claude Code com o Bedrock em uma conta diferente da AWS Se você configurou o Claude Code com uma conta ou perfil da AWS do Bedrock diferente do perfil necessário para se conectar ao seu cluster dsql, você precisará fornecer argumentos de ambiente adicionais: ``` --env AWS_PROFILE="[dsql profile, eg. default]" \ --env AWS_REGION="[dsql cluster region, eg. us-east-1]" \ ``` #### Modificação direta no arquivo de configuração O Claude Code requer nomenclatura alfanumérica, então recomendamos nomear seu servidor: `aurora-dsql-mcp-server`. ##### Escopo local Atualize `~/.claude.json` no campo específico do projeto `mcpServers`: ``` { "projects": { "/path/to/project": { "mcpServers": {} } } } ``` ##### Escopo do projeto Atualize `/path/to/project/root/.mcp.json` no campo `mcpServers`: ``` { "mcpServers": {} } ``` ##### Escopo do usuário Atualize `~/.claude.json` no campo específico do projeto `mcpServers`: ``` { "mcpServers": {} } ``` ### Codex #### Opção 1: CLI do Codex Se você tiver a CLI do Codex instalada, poderá usar o comando codex mcp para configurar seus servidores MCP. ``` codex mcp add amazon-aurora-dsql \ --env FASTMCP_LOG_LEVEL="ERROR" \ -- uvx "awslabs.aurora-dsql-mcp-server@latest" \ --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \ --region "[dsql cluster region, eg. us-east-1]" \ --database_user "[your-username]" ``` #### Opção 2: config.toml Para um controle mais refinado sobre as opções do servidor MCP, você pode editar manualmente o arquivo de configuração `~/.codex/config.toml`. Cada servidor MCP é configurado com uma tabela `[mcp_servers.]` no arquivo de configuração. ``` [mcp_servers.amazon-aurora-dsql] command = "uvx" args = [ "awslabs.aurora-dsql-mcp-server@latest", "--cluster_endpoint", ".dsql..on.aws", "--region", "", "--database_user", "" ] [mcp_servers.amazon-aurora-dsql.env] FASTMCP_LOG_LEVEL = "ERROR" ``` ### Verificar a instalação Para CLI do Amazon Q Developer, CLI do Kiro, CLI/TUI do Claude ou CLI/TUI do Codex, execute `/mcp` para ver o status do servidor MCP. Para o IDE do Kiro, você também pode navegar até a guia `MCP SERVERS` do Painel do Kiro, que mostra todos os servidores MCP configurados e seus indicadores de status de conexão. ## Opções de configuração do servidor ### `--allow-writes` Por padrão, o servidor mcp do dsql não permite operações de gravação (“modo somente leitura”). Todas as invocações da ferramenta de transação falharão nesse modo. Para usar a ferramenta de transação, permita gravações transmitindo o parâmetro `--allow-writes`. Recomendamos usar o acesso com privilégio mínimo ao se conectar ao DSQL. Por exemplo, os usuários devem usar um perfil que seja somente leitura quando possível. O modo somente leitura tem uma aplicação no lado do cliente, em regime de melhor esforço, para rejeitar mutações. ### `--cluster_endpoint` Esse é um parâmetro obrigatório para especificar o cluster ao qual se conectar. Esse deve ser o endpoint completo do seu cluster, por exemplo, `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`. ### `--database_user` Esse é um parâmetro obrigatório para especificar o usuário com o qual se conectar. Por exemplo: `admin` ou `my_user`. Observe que as credenciais da AWS que você está usando devem ter permissão para fazer login como esse usuário. Para acessar mais informações sobre como configurar e usar perfis de banco de dados no DSQL, consulte [Usar perfis de banco de dados com perfis do IAM](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). ### `--profile` Você pode especificar o perfil da aws a ser usado para suas credenciais. Observe que isso não é aceito na instalação do docker. O uso da variável de ambiente `AWS_PROFILE` em sua configuração do MCP também é aceito: ``` "env": { "AWS_PROFILE": "your-aws-profile" } ``` Se nenhum for fornecido, o servidor MCP usa como padrão o perfil “padrão” em seu arquivo de configuração da AWS. ### `--region` Esse é um parâmetro obrigatório para especificar a região do seu banco de dados DSQL. ### `--knowledge-server` Parâmetro opcional para especificar o endpoint remoto do servidor MCP para ferramentas de conhecimento do DSQL (pesquisa, leitura e recomendações de documentação). Por padrão, ele é pré-configurado. Exemplo: ``` --knowledge-server https://custom-knowledge-server.example.com ``` **Observação:** por questões de segurança, use somente endpoints confiáveis do servidor de conhecimento. O servidor deve ser um endpoint HTTPS. ### `--knowledge-timeout` Parâmetro opcional para especificar o tempo limite em segundos para solicitações ao servidor de conhecimento. Padrão: `30.0` Exemplo: ``` --knowledge-timeout 60.0 ``` Aumente esse valor se você tiver tempos limite ao acessar a documentação em redes lentas.