Servidor MCP para AWS Labs Aurora DSQL

Um servidor de protocolo de contexto para modelos (MCP) do AWS Labs para Aurora DSQL

Recursos

Ferramentas disponíveis

Operações de banco de dados

Documentação e recomendações

Pré-requisitos

Instalação

Para a maioria das ferramentas, atualizar a configuração seguindo as instruções de instalação padrão deve ser suficiente.

Há instruções separadas para o Claude Code e o Codex.

Instalação padrão: atualizar o arquivo de configuração do MCP relevante

Usar o uv

Configure o servidor MCP na configuração do seu cliente MCP (Encontrar o arquivo de configuração do MCP)

{
  "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:

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 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 para receber mais detalhes.

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.<server-name>] no arquivo de configuração.

[mcp_servers.amazon-aurora-dsql]
command = "uvx"
args = [
  "awslabs.aurora-dsql-mcp-server@latest",
  "--cluster_endpoint", "<DSQL_CLUSTER_ID>.dsql.<AWS_REGION>.on.aws",
  "--region", "<AWS_REGION>",
  "--database_user", "<DATABASE_USERNAME>"
]

[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.

--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.