Tutorial de servidor MCP: configuração, exemplos e primeira ferramenta para iniciantes

Seu assistente de IA consegue escrever um soneto sobre planilhas, mas, se você perguntar qual é o tamanho de um arquivo no seu notebook, ele não sabe responder. O Model Context Protocol fecha essa lacuna. Um servidor MCP é um pequeno programa que dá ao assistente habilidades reais: ler uma pasta, consultar um banco de dados, chamar uma API e até gerar uma imagem. Este tutorial constrói um servidor a partir de uma pasta vazia, terminando com uma primeira ferramenta funcionando em cerca de vinte minutos e sem nenhuma experiência prévia com protocolos.

Você vai instalar o SDK, escrever uma ferramenta, testá-la no Inspector, conectá-la a um cliente real e, depois, ver como o mesmo padrão alimenta a geração de imagens e vídeos no PicassoIA. Tudo roda em Python puro, então, se você consegue ler uma função, consegue acompanhar.

O que um servidor MCP faz

A analogia com o USB-C

Antes do USB-C, cada dispositivo exigia seu próprio cabo. O MCP faz pela IA o que aquela porta única fez pelo hardware. Sem ele, cada assistente precisava de código sob medida para cada serviço, o que resultava em uma quantidade de cola de integração equivalente a N assistentes vezes M serviços. Com ele, você escreve um servidor e qualquer cliente compatível com MCP pode usá-lo.

A Anthropic apresentou o protocolo no fim de 2024, e desde então muitos aplicativos de chat, editores de código e frameworks de agentes passaram a adotá-lo. Essa adoção é o verdadeiro motivo para se dar ao trabalho: uma ferramenta que você constrói hoje não fica presa a um único produto, e as habilidades que você adquire valem para todo cliente que fala o protocolo.

Host, cliente e servidor

Três papéis aparecem em toda conversa MCP, e iniciantes costumam confundi-los.

As mensagens trafegam como JSON-RPC 2.0. Um servidor local fala por stdio: o host inicia seu script como um processo filho e troca mensagens pelos seus fluxos de entrada e saída. Um servidor remoto fala por Streamable HTTP, que é como funcionam os conectores hospedados.

Veja o que acontece quando você faz uma pergunta:

1. O host inicia seu servidor, e o cliente dele pergunta: "O que você sabe fazer?"
2. O servidor responde com uma lista de ferramentas e o schema de cada uma.
3. Você faz uma pergunta. O modelo decide que uma ferramenta serve e emite uma chamada com argumentos.
4. O host mostra um pedido de permissão e, depois, encaminha a chamada ao seu servidor.
5. Sua função roda, o resultado volta, e o modelo escreve a resposta final.

Ferramentas, recursos e prompts

Um servidor pode oferecer três tipos de coisas, e cada uma tem um dono diferente.

💡 Construa ferramentas primeiro. Elas são a primitiva com suporte mais amplo, e uma ferramenta funcionando ensina a maior parte do que o protocolo exige de você.

Configure seu ambiente

O que você precisa

Reúna quatro coisas antes de digitar qualquer código:

• Python 3.10 ou mais recente. Verifique com python --version.
• Node.js 18 ou mais recente, apenas para o depurador Inspector, que roda por meio de npx.
• Um terminal e qualquer editor de código, mesmo um simples.
• Um cliente MCP, como o Claude Desktop, o Claude Code ou um editor compatível.

Windows, macOS e Linux funcionam. Só muda o comando que ativa o ambiente virtual, e o código abaixo é idêntico em todos os sistemas.

Python ou TypeScript?

Existem SDKs oficiais para várias linguagens. Duas são as apostas mais seguras para um primeiro servidor:

Este tutorial usa Python. Os conceitos, de ferramentas a transportes, valem sem mudanças para qualquer outro SDK.

Escreva sua primeira ferramenta

Crie o projeto

Crie uma pasta, adicione um ambiente isolado e instale o SDK:

mkdir word-counter
cd word-counter
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

Copiar prompt

O extra [cli] instala o comando mcp, que inclui um executor de desenvolvimento para testes rápidos.

Sua ferramenta em 15 linhas

Crie server.py com este conteúdo:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("word-counter")

@mcp.tool()
def count_words(text: str) -> dict:
    """Count the words, characters and lines in a piece of text."""
    return {
        "words": len(text.split()),
        "characters": len(text),
        "lines": len(text.splitlines()),
    }

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

Copiar prompt

Três detalhes fazem todo o trabalho:

1. A docstring é o que o modelo lê para decidir quando chamar a ferramenta. Escreva-a como uma descrição de cargo de uma linha.
2. As dicas de tipo (text: str) viram o schema JSON que informa ao cliente quais argumentos existem e que tipo cada um recebe.
3. O valor de retorno é serializado e enviado de volta ao modelo como resultado da ferramenta.

Quando um cliente se conecta, ele pede ao seu servidor a lista de ferramentas. O FastMCP responde com o nome count_words, sua docstring como descrição e um schema de entrada gerado a partir da assinatura: um objeto com uma propriedade de texto obrigatória chamada text. Esse pequeno documento JSON é tudo o que o modelo sabe sobre sua função, e por isso dar nomes e escrever bem importa mais do que código engenhoso.

💡 Se uma ferramenta nunca é chamada, a causa quase sempre é uma docstring vaga, e não um bug no seu código.

Teste no Inspector

Ainda não conecte um app de chat. Depure no MCP Inspector, uma bancada de testes no navegador:

npx @modelcontextprotocol/inspector python server.py

Copiar prompt

Uma página local se abre. Depois:

1. Clique em Connect para iniciar seu servidor.
2. Abra a aba Tools e pressione List Tools. count_words deve aparecer.
3. Selecione-a, digite uma frase no campo text e execute.
4. Confira se o resultado em JSON mostra as contagens certas.

⚠️ Nunca use print() em um servidor stdio. A saída padrão é o canal de mensagens, e um print esquecido o corrompe. Envie os logs para stderr ou use o módulo logging do Python.

Conecte a um cliente real

Quando o Inspector mostrar verde, registre o servidor em um cliente. Para o Claude Desktop, adicione isto ao arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "word-counter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Copiar prompt

Para o Claude Code, um único comando faz o mesmo trabalho:

claude mcp add word-counter -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Copiar prompt

Reinicie o app por completo e depois pergunte: "Quantas palavras há neste parágrafo?", seguido de algum texto. O cliente pede permissão, executa count_words e responde com os números exatos em vez de um palpite.

Se nada aparecer, verifique estes pontos nesta ordem:

• Apenas caminhos absolutos. Caminhos relativos quebram porque o host inicia o processo a partir da própria pasta.
• Aponte para o interpretador do venv. Um python simples costuma encontrar outra instalação sem o SDK.
• Feche o app por completo. Fechar a janela geralmente o deixa rodando na bandeja.
• Leia os logs. Os clientes gravam logs por servidor que mostram o traceback exato.

Quando um script local já não basta, troque o transporte com mcp.run(transport="streamable-http"), hospede o servidor atrás de HTTPS e adicione autenticação. O código da ferramenta continua exatamente o mesmo, que é o benefício discreto de construir sobre um protocolo.

Três exemplos para copiar

Um recurso somente leitura

Recursos expõem dados por URI. Este serve um arquivo de notas:

from pathlib import Path

@mcp.resource("notes://today")
def todays_notes() -> str:
    """Return the contents of today's notes file."""
    return Path("notes/today.md").read_text(encoding="utf-8")

Copiar prompt

O app pode anexá-lo como contexto sem que o modelo chame nada. Recursos também podem usar modelos de URI como notes://{date}, então uma única função atende a uma família inteira de arquivos.

Um modelo de prompt

Um prompt é um ponto de partida reutilizável que o usuário escolhe em um menu. Diferente de uma ferramenta, o modelo nunca decide executá-lo: o usuário o escolhe, e o resultado vira a mensagem inicial da conversa.

@mcp.prompt()
def review_code(code: str) -> str:
    """Ask for a short, friendly code review."""
    return f"Review this code and list the three most important fixes:\n\n{code}"

Copiar prompt

Uma ferramenta que chama uma API

A maioria dos servidores reais envolve um serviço web. Este verifica se um site está no ar:

import httpx

@mcp.tool()
async def check_site(url: str) -> str:
    """Return the HTTP status code of a website."""
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.get(url, follow_redirects=True)
    return f"{url} answered with status {response.status_code}"

Copiar prompt

httpx já vem com o SDK, e declarar a função como async permite que o servidor continue respondendo enquanto espera pela rede. Chamadas de rede falham, então capture a exceção e devolva uma mensagem curta e legível. Um modelo que vê "o site excedeu o tempo limite de 10 segundos" consegue se adaptar e tentar outra coisa, enquanto um traceback bruto só o confunde.

Erros que desperdiçam sua tarde

Dar bons nomes ajuda tanto quanto a tabela acima. Escolha verbos que digam o que acontece, como count_words ou check_site, mantenha cada ferramenta com uma única tarefa e limite os argumentos aos poucos de que o modelo realmente precisa. Uma ferramenta chamada process com seis campos opcionais é um convite para adivinhar errado.

Proteja o acesso

Uma ferramenta é código que o modelo pode executar na sua máquina, então trate-a com respeito:

• Prefira somente leitura. Adicione ferramentas de escrita ou exclusão apenas quando realmente precisar.
• Valide as entradas. Uma ferramenta de arquivos deve recusar caminhos fora de uma pasta escolhida.
• Mantenha segredos fora do código. Passe os tokens pelo campo env da configuração do cliente, o que os mantém fora do seu repositório.
• Leia o pedido de permissão. Não aprove uma chamada de ferramenta que você não consegue explicar.

Conecte o PicassoIA via MCP

O que o conector oferece

Servidores não se limitam a scripts locais. O PicassoIA expõe a geração de imagens e vídeos para clientes MCP, então um assistente pode criar mídia diretamente de um chat. O conector e a API para desenvolvedores compartilham os mesmos quatro modelos:

Por trás dos panos, a API segue um padrão conhecido: criar uma predição, consultar o status dela e, por fim, buscar o resultado. As requisições usam um token Bearer, os prompts podem ter até 4.000 caracteres, e uma conta roda até 5 predições ao mesmo tempo, compartilhadas entre tokens e conexões MCP. Gerencie as conexões na página MCP da sua conta no PicassoIA e confira no seu plano o que o acesso MCP inclui.

Rascunhe o código da ferramenta com um LLM

Você não precisa escrever cada ferramenta à mão. Modelos de linguagem (LLMs) transformam uma frase simples em um primeiro rascunho que você pode testar no Inspector:

Descreva a ferramenta em uma frase, peça uma versão em FastMCP e execute-a no Inspector antes de confiar nela. Modelos escrevem código plausível, e o Inspector é como você encontra as partes plausíveis, mas erradas.

Gere imagens a partir de um chat

Depois de conectado, o fluxo de trabalho é curto:

1. Abra seu chat com MCP ativado e confirme que o conector do PicassoIA está ativo.
2. Descreva a cena com detalhes concretos: sujeito, lente, luz e clima. Uma linha como "uma caneca de cerâmica sobre uma mesa de carvalho, luz suave de janela vinda da esquerda, lente de 50mm" vence "foto bonita de café".
3. Deixe o assistente chamar a PicassoIA Image e aguarde o resultado.
4. Refine com a PicassoIA Image Editor Pro em vez de começar do zero.
5. Anime o melhor quadro com a PicassoIA Video.

Trate cada prompt como uma lista de verificação curta: sujeito e ação, cenário, direção da luz, lente e textura da superfície. Mantenha uma ideia por imagem e gere em lotes pequenos para ficar dentro do limite de cinco por vez enquanto os primeiros resultados ainda são renderizados.

💡 A geração é assíncrona. Se um cliente mostra "pending", ele está consultando o status, não falhando.

Experimente no Picasso IA hoje

Agora você tem as peças: um servidor, uma primeira ferramenta, um teste no Inspector e a conexão com um cliente. Adicione uma segunda ferramenta esta semana, transforme um dos seus scripts em servidor e veja como seu assistente fica útil rapidamente.

Depois, coloque o lado criativo para funcionar. Acesse o Picasso IA, escolha um modelo como o PicassoIA Image e gere sua primeira imagem a partir de uma única frase. Experimente iluminação, lentes e climas, envie o melhor resultado para o Seedance 2.5 Lite para dar vida a ele e veja até onde vai um bom prompt.