Tutorial · Agentes de IA nas redes sociais

Como criar um servidor MCP: ferramentas, transporte e a primeira chamada

Por Antoine Blanco··7 min de leitura

Um servidor MCP é um programa que responde a tools/list com uma lista de ferramentas e a tools/call executando uma delas. Com o SDK Python são doze linhas. Tudo abaixo foi rodado hoje, 20 de novembro de 2026, no mcp 2.3.0 contra a revisão 2026-07-28 do protocolo, com a saída bruta incluída.

O que um servidor MCP precisa responder

Três coisas, e só a primeira é obrigatória.

Um servidor declara capacidades (tools, resources, prompts), responde a tools/list com um conjunto determinístico de definições de ferramentas, e responde a tools/call executando uma delas e devolvendo conteúdo. Resources e prompts são opcionais. A maioria dos servidores que valem a pena escrever é um saco de ferramentas e nada mais.

A definição de uma ferramenta precisa de um name, uma description e um inputSchema que seja um objeto JSON Schema válido. title, outputSchema e annotations são opcionais. A especificação de ferramentas diz que os nomes devem ter de 1 a 128 caracteres entre letras, dígitos, sublinhado, hífen e ponto, e ser únicos dentro do servidor. Para uma ferramenta sem argumentos, o schema recomendado é {"type": "object", "additionalProperties": false}, nunca null.

Criar um servidor MCP com o SDK Python do MCP

Instale o SDK e o extra de CLI:

pip install "mcp[cli]"      # or: uv add "mcp[cli]"

Esse é o mcp 2.3.0, publicado no PyPI em 2 de outubro de 2026. O ponto de entrada é MCPServer, que substituiu o antigo nome FastMCP:

from mcp.server import MCPServer

mcp = MCPServer("word-count", version="1.0.0")


@mcp.tool()
def count_words(text: str) -> int:
    """Count the words in a block of text."""
    return len(text.split())


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

Três coisas acontecem sem que você escreva nada. A docstring vira a description da ferramenta, a única coisa que o modelo lê para decidir se chama a ferramenta, então escreva para o modelo e não para os seus colegas. As anotações de tipo viram o inputSchema. E a anotação de retorno vira um outputSchema, de modo que o resultado chega em JSON estruturado, não só em texto.

Teste antes de ligar qualquer cliente:

mcp dev server.py

Isso abre o MCP Inspector, que lista as ferramentas e deixa você chamá-las à mão. É o jeito mais rápido de descobrir que um nome de argumento que você achava óbvio não é.

stdio ou Streamable HTTP

mcp.run() usa stdio por padrão. A revisão 2026-07-28 define exatamente dois transportes padrão, e a escolha é sobre quem inicia o processo, não sobre funcionalidades: a semântica do protocolo é idêntica em todos os transportes.

stdio Streamable HTTP
Quem inicia o cliente, como subprocesso você, como serviço
Enquadramento das mensagens JSON-RPC delimitado por quebras de linha no stdin e no stdout um POST HTTP por mensagem
Alcança outras pessoas não sim
Autenticação herda o processo local OAuth ou uma chave de API
Cancelamento notifications/cancelled o cliente fecha o fluxo
Ideal para uma ferramenta na sua própria máquina qualquer coisa que outras pessoas usem

Uma regra que todo mundo quebra no primeiro dia: no stdio, o stdout pertence ao protocolo. Um print() perdido corrompe o fluxo. Mande os logs para o stderr.

Troque de transporte com um único argumento:

mcp.run(transport="streamable-http")
INFO  StreamableHTTP session manager started
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

O endpoint é /mcp, então http://127.0.0.1:8000/mcp.

A primeira chamada do cliente, de verdade

Aponte o cliente do próprio SDK para o servidor stdio:

import asyncio, sys
from mcp import Client, StdioServerParameters

async def main():
    params = StdioServerParameters(command=sys.executable, args=["server.py"])
    async with Client(params) as client:
        print("protocol:", client.protocol_version)
        tools = await client.list_tools()
        for t in tools.tools:
            print("tool:", t.name, "|", t.description)
        res = await client.call_tool("count_words", {"text": "one two three four"})
        print("content:", res.content)
        print("structured:", res.structured_content)

asyncio.run(main())

O que ele imprimiu:

protocol: 2026-07-28
tool: count_words | Count the words in a block of text.
content: [TextContent(type='text', text='4', annotations=None, meta=None)]
structured: {'result': 4}

Repare nas duas grafias. O formato do fio usa camelCase (inputSchema, structuredContent, isError); os objetos Python usam snake_case (input_schema, structured_content, is_error). Ler t.inputSchema levanta um AttributeError, e foi aí que perdi meus cinco primeiros minutos.

Por HTTP, o curl precisa de quatro cabeçalhos, e errá-los é toda a sessão de depuração:

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'mcp-method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'
{"jsonrpc":"2.0","id":1,"result":{"cacheScope":"private","resultType":"complete",
 "tools":[{"description":"Count the words in a block of text.",
 "inputSchema":{"type":"object","properties":{"text":{"title":"Text","type":"string"}},
 "required":["text"],"title":"count_wordsArguments"},"name":"count_words",
 "outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},
 "required":["result"],"type":"object"}}],"ttlMs":0}}

Dois erros que você vai encontrar nessa ordem. Tire o _meta e você recebe -32602: params._meta must be an object carrying the required 'io.modelcontextprotocol/protocolVersion' and 'io.modelcontextprotocol/clientCapabilities' envelope keys. Mantenha o _meta mas esqueça o cabeçalho e você recebe -32020: mcp-method header does not match the request body's method. Um tools/call precisa de um terceiro, mcp-name, que carrega o nome da ferramenta, ou o mesmo -32020 volta.

Com todos eles, a chamada devolve as duas formas:

{"id":2,"result":{"content":[{"text":"4","type":"text"}],"isError":false,
 "resultType":"complete","structuredContent":{"result":4}}}

O que a revisão 2026-07-28 mudou

Se você está seguindo um tutorial escrito para 2025-06-18 ou 2025-11-25, três coisas mudaram de lugar.

Não existe mais o aperto de mão initialize. Cada requisição declara a própria versão de protocolo e as capacidades do cliente em params._meta, e o servidor aceita ou recusa cada requisição de forma independente. O Streamable HTTP espelha esses valores em cabeçalhos para que um proxy possa rotear sem ler o corpo, e o corpo continua sendo a fonte da verdade.

A descoberta é uma única chamada opcional. server/discover devolve de uma vez as versões suportadas, as capacidades e a identidade:

{"id":3,"result":{"capabilities":{"prompts":{"listChanged":true},
 "resources":{"listChanged":true,"subscribe":true},"tools":{"listChanged":true}},
 "supportedVersions":["2026-07-28"]}}

E não existe mais sessão de protocolo. Um servidor não pode guardar estado por conexão, então tudo que atravessa várias chamadas precisa ser um identificador explícito que você devolve de uma ferramenta e aceita como argumento na próxima. Envie uma requisição no formato antigo para este servidor e ele cai no caminho com sessão, que responde Bad Request: Missing session ID. Isso é a compatibilidade retroativa funcionando, não um bug. O que isso significa para o deploy está em hospedagem de servidor MCP.

O caminho de erro que ensina o modelo

A spec divide os erros em dois. Uma requisição malformada ou um método desconhecido é um erro JSON-RPC. Uma falha que o modelo poderia corrigir tentando de outra forma é um resultado de ferramenta com isError: true, porque os clientes devolvem isso ao modelo e ele consegue se corrigir.

O SDK acerta quase tudo sozinho. Uma ferramenta desconhecida devolve um resultado, não um erro de protocolo:

{"id":4,"result":{"content":[{"text":"Unknown tool: nope","type":"text"}],"isError":true}}

Mas levante uma exceção dentro de uma ferramenta e a mensagem é engolida:

raise ValueError("text is empty, pass at least one word")
is_error: True
content: Error executing tool count_words

O modelo agora sabe que a chamada falhou e nada sobre o motivo, então ele tenta de novo com os mesmos argumentos. Se você quer que o modelo se corrija, devolva a explicação no texto da própria ferramenta em vez de levantar uma exceção. Esse único hábito vale mais que todo o trabalho de schema.

Antes de deixar um agente chegar perto

Um servidor que funciona no seu notebook não é um servidor que você entrega para outra pessoa. Faltam duas peças, e cada uma tem a própria página aqui: a autenticação, tratada em OAuth para um servidor MCP, e a decisão de hospedagem. A especificação é direta no resto: valide cada entrada, limite a taxa de invocações, e nunca marque um segredo com x-mcp-header, porque o valor de um cabeçalho fica visível para todos os intermediários do caminho.

Vale também perguntar se você deveria escrever o servidor. Para algo como publicação em redes sociais, o difícil não é o MCP, são oito APIs de plataformas, oito fluxos OAuth e a renovação de tokens: é por isso que o PlugKit mantém um servidor MCP hospedado em https://api.plugkit.co/mcp em vez de entregar um template, a US$ 49 por mês para 5 contas conectadas, cancele quando quiser, ou US$ 97 por mês para 30, depois de sete dias gratuitos com cartão pedido no cadastro e nada cobrado antes do dia 7. Verificado em 20 de novembro de 2026. Escreva o seu quando as ferramentas são suas: seu banco de dados, sua API interna, seu sistema de build. MCP ou API REST para o seu agente é a decisão um nível acima, e servidor MCP do Instagram é a aparência do resultado final visto do cliente.

Perguntas frequentes

Em que linguagem escrever um servidor MCP?

Aquela em que suas ferramentas já vivem. A lista oficial de SDKs tem dez: TypeScript, Python, C#, Go, Rust e Ruby no tier 1, Java no tier 2, Swift, PHP e Kotlin no tier 3, sendo o tier o quanto cada um é completo e mantido. Todos falam o mesmo JSON-RPC. O servidor é uma casca fina em volta de código que você já tem, então reescrever esse código em outra linguagem é o erro caro.

Preciso de Streamable HTTP ou stdio basta?

o stdio basta quando o único usuário é você nesta máquina: o cliente inicia seu script como subprocesso e nada fica exposto. No momento em que uma segunda pessoa ou um agente hospedado precisa dele, você precisa de Streamable HTTP, uma URL e autenticação.

Como testar um servidor MCP sem cliente?

mcp dev server.py abre o MCP Inspector, que lista suas ferramentas e as chama com os argumentos que você digita. Depois disso, curl contra o endpoint HTTP mostra o JSON exato que um cliente real envia, e é assim que você pega um schema que o modelo vai ler errado.

Por que minha ferramenta funciona no Inspector mas não no agente?

Normalmente a descrição. O modelo escolhe ferramentas lendo a description e os títulos dos argumentos, e uma docstring tipo "cuida da coisa" não dá nada para ele se apoiar. Reescreva a docstring como uma instrução, diga o que a ferramenta devolve, e nomeie os argumentos como quem chama adivinharia.

Quantas ferramentas um servidor MCP deveria expor?

Menos do que você quer. Cada definição ocupa o contexto do modelo em todo turno, então cem ferramentas custam tokens reais e confusão real entre quase duplicatas. Agrupe por tarefa, devolva conteúdo estruturado para que uma ferramenta responda a várias perguntas, e separe em vários servidores antes de picar um servidor em cem nomes.

AB
Antoine BlancoFundador da PlugKit. Gerencia as próprias contas de Instagram, YouTube e X pela API e pelo servidor MCP descritos aqui.

Um plug para cada plataforma que seu agente usa

$49 por mês para 5 contas conectadas, cancele quando quiser. Todos os recursos em todos os planos.

Pegue sua chave de API →
Português ▾