Python 20/03/2026

Como conectar seu servidor MCP ao VS Code para usar com o Codex

No post anterior, eu montei um servidor MCP simples em Python para listar processos, consultar detalhes de um PID e encerrar processos com algum cuidado.

Agora vamos fazer a parte que fecha o ciclo: conectar esse servidor ao VS Code para que o Codex consiga chamar as tools direto do editor.

A ideia aqui é bem prática:

• manter o servidor MCP funcionando localmente;
• registrar esse servidor na configuração do Codex;
• abrir o VS Code e conversar com o agente usando as funções expostas pelo seu servidor.

Antes de começar

Você vai precisar de:

• o projeto do post anterior criado e funcionando;
• VS Code instalado;
• a extensão do Codex instalada;
• login feito na extensão com sua conta ChatGPT ou com API key.

Este post esta falando da extensão do Codex no VS Code. Ela compartilha a mesma configuração do Codex CLI, então o cadastro do servidor MCP fica em ~/.codex/config.toml ou em .codex/config.toml no projeto.

Primeiro valide o servidor fora do editor

Antes de culpar o VS Code, vale confirmar que o servidor sobe normalmente no terminal:

cd /home/seu-usuario/projetos/mcp-process-monitor
source .venv/bin/activate
python server.py

Se ele iniciar sem stack trace, já é um bom sinal. Pode interromper com Ctrl+C depois desse teste.

Instale e abra o Codex no VS Code

Instale a extensão do Codex pelo marketplace do VS Code. Depois disso:

• abra o projeto no editor;
• clique no ícone do Codex na barra lateral;
• faça login quando a extensão pedir;
• reinicie o VS Code se o painel não aparecer logo de cara.

Se você usa Windows, o caminho mais seguro hoje e abrir o projeto em WSL e usar os caminhos Linux dentro dele.

Registrando o servidor MCP no Codex

O jeito mais rápido de adicionar o servidor é pelo CLI do Codex. Como o nosso servidor é do tipo STDIO, o que o Codex precisa saber é basicamente qual comando executar para subí-lo.

codex mcp add process-monitor -- \
  /home/seu-usuario/projetos/mcp-process-monitor/.venv/bin/python \
  /home/seu-usuario/projetos/mcp-process-monitor/server.py

Alguns detalhes importantes:

• use caminhos absolutos;
• aponte para o Python da sua virtualenv, não para o Python global;
• troque process-monitor pelo nome que fizer mais sentido para voce.

Se preferir editar a configuração manualmente, abra o config.toml pelo menu de engrenagem da extensão e adicione algo assim:

[mcp_servers.process_monitor]
command = "/home/seu-usuario/projetos/mcp-process-monitor/.venv/bin/python"
args = ["/home/seu-usuario/projetos/mcp-process-monitor/server.py"]
cwd = "/home/seu-usuario/projetos/mcp-process-monitor"

Nesse formato:

• command é o executável que sobe o servidor;
• args recebe os argumentos desse comando;
• cwd ajuda quando o servidor depende do diretório correto para abrir arquivos locais.

Global ou por projeto?

Se você quer esse servidor disponível em qualquer workspace, deixe a configuração em:

~/.codex/config.toml

Se você quer limitar ao repositório atual, use:

.codex/config.toml

Esse segundo caso e bem interessante quando o MCP só faz sentido naquele projeto. A única observação é que o Codex só carrega a configuração local quando o projeto está marcado como confiável.

Testando dentro do VS Code

Depois de salvar a configuração:

• recarregue a janela do VS Code, se necessário;
• abra o painel do Codex;
• envie um prompt pedindo para usar as tools do servidor.

Alguns testes simples:

Chame a tool listar_processos com limite=10 e organize a resposta em tabela.

Abaixo esta um exemplo real desse primeiro comando funcionando no VS Code com o Codex:

Use a tool detalhes_processo para inspecionar o PID 1234 e resuma o resultado em português.

Não encerre nada ainda. Primeiro me diga o que você faria com a tool encerrar_processo no PID 1234 e espere minha confirmação.

Em geral, o Codex consegue decidir sozinho quando usar uma tool. Mesmo assim, nos primeiros testes eu gosto de citar o nome da função explicitamente para validar o encadeamento.

Problemas comuns

• Caminho errado para a virtualenv: o Codex não consegue iniciar o servidor.
• Dependências fora da .venv: o comando sobe, mas quebra logo em seguida.
• Projeto não confiável: o .codex/config.toml local é ignorado.
• VS Code sem reload: a extensão pode continuar com a configuração antiga.

Se o seu servidor precisar de variáveis de ambiente, você tambem pode adicioná-las na configuração do MCP mais tarde.

Fechando

Com isso, aquele servidor MCP em Python deixa de ser só um exemplo isolado e passa a virar uma extensão prática do seu ambiente de desenvolvimento. O ganho real está aqui: em vez de abrir terminal, rodar scripts soltos e interpretar saída manualmente, você pode pedir ao Codex para consultar e operar nas tools do seu próprio servidor.

Se quiser evoluir essa idéia, o proximo passo natural é enriquecer o servidor com mais contexto, como filtros por nome de processo, leitura de consumo histórico e regras de segurança antes de executar ações destrutivas.