O que é MCP (Model Context Protocol)

Um modelo de linguagem sozinho só conhece o que estava no treinamento e no prompt. Para ler seu banco de dados, consultar um calendário ou abrir um issue no GitHub, ele precisa de uma ponte até esses sistemas. Sem um padrão comum, cada aplicativo de IA escreve essa ponte por conta própria, serviço por serviço.

O MCP (Model Context Protocol) é esse padrão comum. A documentação oficial o compara a uma porta USB-C para aplicações de IA: um conector só, no lugar de um cabo diferente para cada aparelho.

O que o MCP resolve?#

Sem padrão, conectar N aplicativos de IA a M serviços exige até N vezes M integrações, cada uma com seu formato. Com o MCP, cada aplicativo implementa o lado cliente uma vez e cada serviço implementa o lado servidor uma vez. A partir daí, qualquer um conversa com qualquer outro.

O protocolo trata só da troca de contexto. Como o aplicativo usa o modelo e conduz a conversa fica a cargo de quem o constrói. Se você ainda não viu como um modelo funciona, comece por o que é um LLM.

Segundo a documentação, o MCP já é suportado por assistentes como Claude e ChatGPT e por ferramentas de desenvolvimento como Visual Studio Code e Cursor.

Quais são as peças do MCP?#

São três papéis:

• Host: a aplicação de IA que o usuário abre, como um assistente de chat ou um editor de código.
• Cliente: um componente dentro do host que mantém a conexão com um servidor. O host cria um cliente por servidor.
• Servidor: o programa que fornece contexto e funções. Pode rodar na sua máquina ou em outro lugar.

Um exemplo da documentação: o Visual Studio Code é o host. Ao se conectar a um servidor do Sentry, ele cria um cliente para esse servidor; ao se conectar a um servidor de sistema de arquivos, cria outro.

As mensagens usam JSON-RPC 2.0, um formato de chamada remota. Se você conhece APIs REST, a diferença é que aqui o contrato inclui descoberta: o cliente pergunta ao servidor o que ele sabe fazer.

O que um servidor MCP oferece?#

Um servidor expõe até três tipos de recurso:

Cada tipo tem métodos de listagem (tools/list, por exemplo) e, no caso das tools, de execução (tools/call). Como o cliente lista os recursos em tempo de execução, o servidor pode mudar o que oferece sem que ninguém reescreva o aplicativo.

As tools são o recurso mais usado. Cada uma tem um nome, uma descrição em texto e um esquema JSON dos argumentos. O modelo lê a descrição para decidir quando chamá-la, por isso uma descrição clara pesa tanto quanto o código.

Como cliente e servidor se comunicam?#

O protocolo tem duas camadas: a de dados (as mensagens JSON-RPC) e a de transporte (como elas viajam). Há dois transportes padrão:

• stdio: o cliente inicia o servidor como um processo local e troca mensagens pela entrada e saída padrão. É o transporte dos servidores locais, sem rede.
• Streamable HTTP: cada mensagem é um POST HTTP para um único endpoint, como https://exemplo.com/mcp. A resposta chega como um objeto JSON ou como um fluxo SSE. É o transporte dos servidores remotos, que atendem muitos clientes.

Desde a revisão 2026-07-28 da especificação, o protocolo é sem estado: cada requisição leva a versão do protocolo e as capacidades do cliente, e o servidor responde server/discover para anunciar o que suporta. Versões anteriores usavam um handshake initialize e sessões. O antigo transporte HTTP+SSE está obsoleto.

No nível do protocolo, uma chamada de tool é um JSON como este (os campos _meta com versão e capacidades foram omitidos):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": { "location": "San Francisco", "units": "imperial" }
  }
}

A resposta traz uma lista content com blocos de conteúdo, como texto, imagem ou recurso. Na prática você não escreve esse JSON: você escreve uma função e o SDK monta as mensagens.

Como criar um servidor MCP mínimo?#

Com o SDK oficial em Python, uma tool é uma função com tipos e docstring. Crie o projeto e instale o SDK:

uv init pedidos
cd pedidos
uv add "mcp[cli]"

Em pedidos.py:

from mcp.server import MCPServer

mcp = MCPServer("pedidos")

PEDIDOS = {  # dados de exemplo, no lugar de um banco real
    "1001": "enviado",
    "1002": "aguardando pagamento",
}


@mcp.tool()
async def status_do_pedido(numero: str) -> str:
    """Consulta o status de um pedido.

    Args:
        numero: Número do pedido, por exemplo 1001
    """
    return PEDIDOS.get(numero, "pedido não encontrado")


if __name__ == "__main__":
    mcp.run(transport="stdio")

Rode uv run pedidos.py para iniciar o servidor em stdio. Para testar sem um aplicativo de IA, use o MCP Inspector, a ferramenta oficial de depuração.

Para conectar ao Claude Desktop, adicione o servidor ao arquivo claude_desktop_config.json, trocando o caminho pelo seu:

{
  "mcpServers": {
    "pedidos": {
      "command": "uv",
      "args": ["--directory", "/caminho/para/pedidos", "run", "pedidos.py"]
    }
  }
}

Reinicie o aplicativo e a tool passa a aparecer. Em stdio, nunca escreva logs com print() na saída padrão: é por ela que passam as mensagens do protocolo, e qualquer texto extra corrompe a conversa. Use stderr.

O SDK oficial em TypeScript (@modelcontextprotocol/server) segue o mesmo desenho: você registra tools com um esquema zod e serve por stdio.

Quais são os riscos e limites?#

O MCP dá ao modelo a capacidade de agir, e isso pede cuidado. A especificação recomenda manter sempre uma pessoa no circuito, com poder de negar chamadas de tools. O aplicativo deve mostrar ao usuário quais tools estão expostas e pedir confirmação em operações sensíveis.

• Permissões demais: um servidor com acesso de escrita ao banco pode apagar dados se o modelo errar. Dê só o acesso necessário e, sempre que puder, prefira tools somente de leitura.
• Servidor não confiável: a especificação manda o cliente tratar as anotações de tools como não confiáveis, a menos que venham de um servidor confiável. Instale só servidores de fontes que você audita.
• Injeção de prompt: texto vindo de um e-mail, página ou issue pode conter instruções que tentam enganar o modelo para chamar tools que você não queria. Aprovação humana em ações destrutivas é a defesa mais simples.
• Servidor remoto exposto: valide o cabeçalho Origin, exija autenticação e, se rodar localmente, escute só em 127.0.0.1, como a especificação recomenda.

Nem todo projeto precisa de MCP. Com um único aplicativo e três funções, declará-las direto na API do modelo é mais simples. O protocolo compensa quando as mesmas ferramentas servem a vários clientes.

Como o MCP se relaciona com outros termos?#

• Function calling / tool use: é o recurso do modelo de pedir a execução de uma função. O MCP padroniza de onde as funções vêm e como o aplicativo as executa.
• Agente: um sistema em que o modelo decide, em loop, quais tools chamar. Agentes costumam usar servidores MCP como fonte de tools.
• API REST: um servidor MCP frequentemente embrulha uma API REST, traduzindo-a em tools que o modelo entende.

Se a sua tool vai gerar custo por chamada de modelo, veja também quanto custa usar a API de um LLM.

Como fazer isso na Square Cloud#

Um servidor stdio roda na máquina de quem usa e não precisa de hospedagem. Um servidor remoto, em Streamable HTTP, é uma aplicação web como outra qualquer: um processo que escuta HTTP e precisa estar no ar sempre que um cliente chamar. Na Square Cloud, ele roda num container isolado e sempre ligado, sem cold start nem modo de suspensão, com um subdomínio *.squareweb.app e HTTPS. O proxy na frente das aplicações deixa respostas SSE passarem sem buffer, o que importa quando uma tool transmite o próprio progresso.

Para publicar o servidor de pedidos no runtime de Python, liste mcp num requirements.txt (no start, a plataforma roda pip install -r requirements.txt), troque o transporte stdio por Streamable HTTP e faça o servidor escutar em 0.0.0.0, na porta da variável PORT. É o oposto do servidor local, que escuta só em 127.0.0.1: aqui o endpoint é público, então validar o Origin e exigir autenticação passam a ser obrigação do seu código. Tokens e chaves ficam nas variáveis de ambiente da aplicação. Uma aplicação web usa no mínimo 512 MB do pool de RAM do plano, e o Hobby custa a partir de R$ 12,49 por mês. O passo a passo de deploy está em como hospedar uma API.

Do lado do modelo, se você constrói o próprio agente (host e cliente), o AI Gateway pode ser o LLM que decide quais tools chamar. É uma API compatível com a OpenAI para o modelo cubic, com function calling no formato da OpenAI, até 32 tools por requisição. O cliente converte cada tool do MCP (nome, descrição e esquema JSON) numa definição de função; quando a resposta volta com tool_calls, ele chama tools/call no servidor MCP e devolve o resultado numa mensagem role: "tool". O gateway está em beta, sem custo extra durante o beta, e vem a partir do plano Standard, com até 2,5M tokens por dia e contexto de até 16k tokens, em que as definições de tools também contam. Limites e disponibilidade podem mudar quando o beta acabar. Para o servidor em si, veja a página de hospedagem de APIs.