“Aquele servidor está desligado?”, “Qual compartment eu posso usar para o meu teste?”, “Qual subnet essa VM utiliza?”

Quem trabalha com infraestrutura provavelmente já recebeu perguntas assim e precisou abrir a console, fazer login, selecionar a região e procurar o recurso para responder. Pelo CLI, o caminho muda, mas ainda é preciso montar o comando e informar os parâmetros certos.

Agora imagine fazer essas perguntas diretamente ao Codex: consultar a configuração do servidor, entender em qual rede ele está ou preparar uma nova VM para um teste e antes de qualquer alteração, você revisa a proposta e decide se ela pode ser executada ou não.

Neste post, vamos usar o Codex para demonstrar essa integração com a Oracle Cloud Infrastructure por meio de um MCP Server. A mesma abordagem pode ser utilizada com outros clientes compatíveis com MCP, como Claude Desktop, Cursor ou VS Code com GitHub Copilot, ajustando a configuração de cada ferramenta.

Nota: os servidores disponibilizados no repositório Oracle MCP são implementações de referência para exploração, prototipação e aprendizado, sem destinação a uso em produção. Execute os exemplos em um ambiente de testes. Consulte o escopo do projeto.

Como Codex, MCP e OCI trabalham juntos

O Model Context Protocol, ou MCP, permite que uma aplicação de IA descubra e utilize ferramentas oferecidas por um servidor.

O diagrama abaixo mostra o papel de cada componente e o caminho percorrido pelos pedidos e pelas respostas:

Pré-requisitos

Os exemplos de configuração abaixo usam Windows e PowerShell. Antes de começar, tenha:

  • Codex instalado, autenticado e com suporte a servidores MCP locais.
  • Acesso a uma tenancy OCI (não produtiva)
  • Credenciais OCI válidas
  • OCI CLI instalado e configurado.

Preparando a autenticação e as permissões

Configure o acesso local à OCI

Para acessar sua tenancy, o servidor MCP precisa de credenciais OCI. Neste tutorial, vamos utilizar autenticação por chave de API, com um perfil de configuração salvo no computador.

Usaremos o OCI CLI para preparar esse perfil, que também será utilizado pelo servidor MCP. Se você já possui um perfil configurado e funcionando, pode seguir para a preparação do servidor MCP, na próxima seção.

Caso seja seu primeiro acesso pelo CLI, siga o guia oficial de instalação e configuração.

Conclua o cadastro da chave pública no usuário OCI conforme o procedimento oficial de configuração de chaves de API.

Ao finalizar, confira se existe um perfil DEFAULT válido no arquivo %USERPROFILE%\.oci\config. Ele deve conter os dados da identidade e a referência à chave privada. Se você utilizar outro nome de perfil, informe esse nome também na configuração do MCP.

Mantenha a chave privada protegida no computador. O arquivo de configuração deve referenciar seu caminho; não copie o conteúdo da chave para a conversa ou para o projeto.

Conectando o OCI Cloud MCP Server ao Codex

O OCI Cloud MCP Server é uma aplicação Python executada no seu computador. Ele disponibiliza ferramentas ao Codex e utiliza o SDK Python para realizar chamadas às APIs da OCI. Nesta etapa, vamos preparar suas dependências e configurar sua inicialização.

Vamos usar o uv para gerenciar o Python e o ambiente de execução. O uv também inclui o uvx, que obtém aplicações Python e suas dependências em ambientes isolados e as executa quando solicitado.

Instale o uv

Abra o PowerShell e execute:

winget install --id=astral-sh.uv -e

Depois da instalação, feche e abra novamente o PowerShell para que ele reconheça o caminho dos executáveis. Confirme que as duas ferramentas estão disponíveis:

uv --version
uvx --version

Cada comando deve retornar a versão instalada. Se algum deles não for reconhecido, confira se a instalação foi concluída e se o diretório dos executáveis está no PATH do Windows.

Instale uma versão compatível do Python

A versão do servidor MCP utilizada neste tutorial exige Python 3.13 ou superior. Vamos preparar a versão 3.13 com o próprio uv:

uv python install 3.13

Para conferir se ela foi localizada, execute:

uv python find 3.13

Utilizaremos o pacote oracle.oci-cloud-mcp-server publicado no PyPI. Quando o Codex executar o comando configurado, o uvx preparará o pacote e suas dependências em um ambiente isolado e iniciará o servidor.

Abra o arquivo de configuração do Codex

O Codex armazena suas configurações de usuário no arquivo config.toml. No Windows, o caminho padrão é:

%USERPROFILE%\.codex\config.toml

Esse arquivo pode conter outras configurações do Codex. Mantenha o conteúdo existente e acrescente a configuração abaixo ao final. Se já houver uma seção chamada [mcp_servers.oci-cloud], atualize essa seção em vez de duplicá-la. Documentação de configuração MCP do Codex.

Adicione a configuração do servidor

[mcp_servers.oci-cloud]
command = "uvx"
args = [
  "--python",
  "3.13",
  "oracle.oci-cloud-mcp-server@latest"
]
startup_timeout_sec = 120
tool_timeout_sec = 180
default_tools_approval_mode = "prompt"

[mcp_servers.oci-cloud.env]
OCI_CONFIG_FILE = "C:/Users/SEU_USUARIO/.oci/config"
OCI_CONFIG_PROFILE = "DEFAULT"
OCI_REGION = "sa-saopaulo-1"
OCI_MCP_AUTH_TYPE = "api_key"

Ajuste os dados do seu ambiente OCI

A seção [mcp_servers.oci-cloud.env] fornece ao servidor as informações de autenticação e região:

ConfiguraçãoO que preencher
OCI_CONFIG_FILECaminho completo do arquivo de configuração OCI preparado anteriormente.
OCI_CONFIG_PROFILENome do perfil existente nesse arquivo. Neste exemplo, DEFAULT.
OCI_REGIONRegião em que serão realizadas as operações.
OCI_MCP_AUTH_TYPEMétodo de autenticação. Usaremos api_key, conforme configurado na etapa anterior.

Observação: Durante os testes com a versão 2.3.0 no Windows, foi necessário criar manualmente a pasta C:\tmp, utilizada para gravar o arquivo de log /tmp/audit.log. Esse comportamento pode variar entre versões.

Inicie a conexão

Reinicie o Codex para carregar a configuração. Na primeira inicialização, o uvx poderá precisar baixar o pacote e suas dependências. Mantenha acesso à internet e acompanhe eventuais mensagens de erro.

Confira se o servidor foi reconhecido

Em uma nova conversa no Codex, peça:

Verifique se o servidor MCP oci-cloud está conectado e liste as ferramentas disponíveis nele. Não execute operações na OCI ainda.

Faça a primeira consulta à OCI

Com o servidor reconhecido, vamos verificar se ele consegue acessar os recursos do seu ambiente.

Você pode informar o compartment pelo nome, o Codex irá localizá-lo e obter o identificador necessário para realizar a consulta. Se ele estiver dentro de outro compartment, informe o caminho na hierarquia, como Projetos/Testes.

Substitua esse exemplo pelo caminho do seu compartment e faça o pedido:

Use o servidor MCP oci-cloud para localizar o compartment Projetos/Testes e listar as VMs na região sa-saopaulo-1. Apresente nome, estado e shape. Se houver mais de um compartment correspondente, peça esclarecimento antes de continuar. Verifique se existem outras páginas de resultados e faça apenas consultas, sem alterar recursos. Se a chamada MCP falhar, explique o erro antes de tentar outro meio de acesso.

Esse teste verifica o caminho completo: Codex → servidor MCP → OCI. Uma resposta bem-sucedida confirma o acesso àquela consulta.

Registrando instruções com o AGENTS.md

Você também pode usar o arquivo AGENTS.md, na pasta do projeto, para registrar instruções que o Codex deve considerar durante o trabalho. Conheça o funcionamento do AGENTS.md.

O exemplo abaixo reúne algumas orientações para operar recursos OCI. Customize as regras conforme suas necessidades:

# Operações OCI

## Contexto do ambiente
- Região: sa-saopaulo-1.
- Utilizar o servidor MCP oci-cloud para acessar a OCI.

## Regras de operação
- Consultar o estado atual antes de propor mudanças.
- Antes de criar, modificar ou excluir recursos, apresentar os parâmetros, os recursos afetados e obter aprovação explícita.
- Solicitar nova aprovação se o escopo da alteração mudar.
- Preservar recursos compartilhados e configurações fora do escopo.
- Não exibir chaves privadas, tokens ou senhas.
- Informar quando uma consulta retornar resultados parciais.
- Verificar o resultado após executar uma alteração.
- Se o MCP falhar, explicar o problema antes de utilizar outro meio de acesso.

Depois de salvar, peça ao Codex:

Leia o AGENTS.md deste projeto e confirme qual região e servidor MCP serão utilizados. Resuma também as regras para alterações de recursos. Não execute operações na OCI neste momento.

Confira se a resposta corresponde ao que você registrou. Essas instruções passam a orientar o trabalho no projeto.

Consultando recursos com linguagem natural

Com a integração funcionando, podemos começar a explorar o ambiente de forma natural. Abaixo alguns exemplos:

Listar as maiores instâncias

Liste as três maiores instâncias acessíveis na região sa-saopaulo-1, ordenadas por OCPUs alocadas e, em caso de empate, por RAM. Apresente nome, OCPUs, RAM e compartment. Informe eventuais limitações da consulta.

Investigar um problema de acesso

Não estou conseguindo acessar a VM de teste “XXXXX” via RDP no compartment “XXXXX”. Identifique o possível motivo.

Após apresentar o diagnóstico, o Codex aguardou minha aprovação antes de alterar a configuração de rede, seguindo as orientações registradas no AGENTS.md.

Criar instâncias

Quero criar uma VM com 1 OCPU, 1 GB de RAM e Oracle Linux 8 no compartment de testes. Consulte as opções disponíveis, peça as informações que faltarem e apresente uma proposta.

Segurança e controle das operações

Ao conectar o Codex à OCI, as permissões das credenciais utilizadas passam a ser um ponto central da configuração. No modo local apresentado neste tutorial, as operações são realizadas com as permissões da identidade associada ao perfil OCI selecionado. Por isso, utilize apenas os acessos necessários para os recursos que pretende consultar ou administrar. Consulte as orientações de autenticação e segurança do projeto.

Alguns cuidados ajudam a manter o controle:

  • Comece com consultas. Confirme a região, o compartment e os recursos envolvidos antes de solicitar alterações.
  • Revise a proposta antes de aprovar. Confira parâmetros, recursos afetados, custos e dependências. Em regras de rede, verifique também quais outros recursos compartilham o NSG ou a lista de segurança.
  • Limite o acesso de rede. Libere somente as portas e origens necessárias.
  • Proteja credenciais e dados do ambiente. Não cole chaves privadas, tokens ou senhas na conversa. Antes de compartilhar capturas ou logs, remova informações sensíveis e verifique as políticas da sua organização para o uso de ferramentas de IA.
  • Combine instruções com controles técnicos. O AGENTS.md ajuda a registrar contexto e regras de operação, mas não substitui as permissões IAM nem os controles de aprovação do cliente.
  • Verifique o resultado. Após uma alteração, consulte novamente o recurso e faça o teste adequado. Uma porta acessível, por exemplo, não comprova que o login na aplicação funcionará.

Considerações importantes

O servidor utilizado faz parte do repositório público oracle/mcp, mantido na organização Oracle no GitHub. Entretanto, o próprio projeto apresenta seus servidores como implementações de referência para exploração, prototipagem e aprendizado, sem destinação ao uso em produção. Essa condição deve ser considerada antes de aplicar a integração em outros ambientes. Consulte o escopo declarado pelo projeto.

Os resultados deste tutorial refletem as permissões, a região e os recursos disponíveis no ambiente utilizado. Uma listagem pode não representar toda a tenancy, e uma hipótese de diagnóstico precisa ser confirmada pelos dados e testes disponíveis.

A execução de um pedido também pode gerar custos ou afetar recursos compartilhados. Revise cada operação e, ao terminar os testes, confira quais recursos devem permanecer e quais podem ser excluídos.

Conclusão

Neste artigo, conectamos o Codex à OCI via MCP e exploramos situações comuns de quem administra infraestruturas em nuvem.

Você pode adaptar esses exemplos à sua rotina, começando por consultas e avançando para alterações com revisão e aprovação. O cuidado permanece o mesmo: saber em qual ambiente estamos trabalhando, entender o que será executado e conferir o resultado.

Referências