MCP na Prática — Parte 9: Dos Conceitos a um Exemplo Prático

Parte 9 da Série MCP na Prática · Voltar: Parte 8 — Seu Servidor MCP Está Autenticado. Não É Seguro Ainda.

Na Parte 5, você construiu um servidor MCP funcional. Três ferramentas, dois recursos, dois prompts e um cliente local — todos conectados via stdio. O protocolo funcionou. O assistente de pedidos respondeu perguntas, procurou pedidos e cancelou um.

Então, as Partes 6 a 8 explicaram o que muda quando esse servidor sai da sua máquina: implantação em produção, decisões de transporte, autenticação e os riscos de segurança que vêm com o próprio protocolo. Esses foram artigos conceituais. Eles explicaram o raciocínio. Não mudaram o código.

Esta parte fecha a lacuna. Pegamos o mesmo assistente de pedidos TechNova e o movemos de stdio para HTTP Streamable. Mesmas ferramentas. Mesma lógica de negócios. Mesmas mensagens de protocolo. Transporte diferente, modelo de implantação diferente e um conjunto diferente de preocupações em torno disso.

Esta não é a Parte 5 novamente. É a transição que as Partes 6–8 prepararam você.

Por Que Esta Parte Existe

A Parte 5 deu a você um servidor local funcional. As Partes 6 a 8 explicaram o que muda na produção. Esta parte final junta esses dois lados.

A Parte 9 preenche essa lacuna com um exemplo focado. Não está tentando construir uma implantação pronta para produção. Está tentando mostrar a transição de forma clara o suficiente para que um desenvolvedor que seguiu a série possa ver exatamente o que muda e o que permanece o mesmo.

Se a Parte 5 foi "construa localmente", esta parte é "agora execute como um serviço".

O Mesmo Exemplo, um Modelo de Implantação Diferente

Esquerda: Parte 5 — host lança o servidor como um processo filho na mesma máquina. Direita: Parte 9 — servidor roda independentemente, clientes se conectam via HTTP.

O assistente de pedidos TechNova é o mesmo. As mesmas três ferramentas: get_order_status, get_order_items, cancel_order. Os mesmos dois recursos: pedido por ID e resumo de pedidos recentes. Os mesmos dois prompts. Os mesmos dados de pedidos semeados. O mesmo fluxo de trabalho de negócios.

O que muda é como o servidor roda e como os clientes o alcançam. Na Parte 5, o host lançou o servidor como um processo filho. A comunicação acontecia via stdin e stdout. A confiança era herdada da máquina local. Nenhuma rede estava envolvida.

Nesta parte, o servidor roda como um serviço HTTP independente. Ele escuta em uma porta. Os clientes se conectam a ele pela rede — ou, para este walkthrough, via localhost. As mensagens MCP são idênticas. O modelo de implantação é completamente diferente.

O Que Muda Quando Você Passa de stdio para HTTP Streamable

O protocolo não muda. As mesmas mensagens JSON-RPC fluem entre cliente e servidor. A mesma sequência de inicialização → lista → chamada acontece. O servidor ainda expõe ferramentas, recursos e prompts. O cliente ainda os descobre e os invoca.

O que muda é tudo ao redor do protocolo. Em stdio, o host controlava o ciclo de vida do servidor — ele iniciava o processo e o parava. Com HTTP Streamable, o servidor já está em execução. O cliente não o inicia; o cliente se conecta a ele.

Essa única mudança — de iniciar um processo para se conectar a um serviço — é o motivo pelo qual as Partes 6 a 8 existem. Uma vez que o servidor é um serviço independente, você precisa pensar sobre quem pode se conectar, como eles provam identidade, o que cada chamador pode fazer e se as descrições das ferramentas do servidor podem ser confiáveis.

Para este walkthrough, pulamos autenticação e segurança. Estamos rodando em localhost. O objetivo é ver a transição de transporte claramente, sem preocupações de produção obscurecendo a imagem. As Partes 6–8 já cobriram o que você adicionaria a seguir.

O Lado do Servidor

O servidor da Parte 5 (server.py) terminou com uma linha que escolheu o transporte. O servidor da Parte 9 (server_http.py) muda essa única linha:

# Parte 5 — stdio (processo local)
app.run(transport="stdio")

# Parte 9 — HTTP Streamable (serviço independente)
app.run(transport="streamable-http")

O servidor agora roda como um serviço HTTP em http://127.0.0.1:8000/mcp — o endpoint padrão para este exemplo. Quando um cliente envia uma solicitação POST para esse endpoint com uma mensagem JSON-RPC, o servidor a processa e retorna a resposta.

Tudo acima dessa linha permanece o mesmo. As definições de ferramentas, os manipuladores de recursos, os templates de prompts, os ajudantes de dados — nada disso muda. A lógica de negócios do servidor não sabe nem se importa qual transporte está carregando suas mensagens.

Esse é o objetivo da abstração de transporte do MCP. Você escreve suas ferramentas uma vez. O transporte é uma decisão de implantação, não uma decisão de código. A Parte 7 explicou isso conceitualmente. Aqui você vê isso na prática: uma linha mudou, e o servidor agora é um serviço de rede em vez de um processo filho.

Executando e Testando Localmente

Abra dois terminais. No primeiro, inicie o servidor:

bash run_server.sh

Na primeira execução, o script cria um ambiente virtual, instala dependências, semeia os dados de pedidos e inicia o servidor HTTP Streamable. Você deve ver: "Endpoint: http://127.0.0.1:8000/mcp" — o servidor agora está ouvindo.

Se você quiser validar o endpoint com o MCP Inspector antes de executar o cliente, o README do GitHub inclui um breve walkthrough do Inspector e um exemplo de como uma conexão bem-sucedida se parece.

O Lado do Cliente

Na Parte 5, client.py lançou o servidor como um subprocesso e se comunicou via stdio. A conexão era implícita — stdin e stdout eram o canal.

Na Parte 9, client_http.py se conecta a uma URL em vez disso. Onde a Parte 5 importava stdio_client, o novo cliente importa streamable_http_client do SDK MCP e o aponta para http://127.0.0.1:8000/mcp. A conexão é explícita: você informa ao cliente onde encontrar o servidor.

No segundo terminal, execute: