Criar um servidor MCP do zero não precisa começar por uma arquitetura gigante. O melhor primeiro servidor e pequeno: uma ou duas ferramentas uteis, entrada bem definida, saida previsivel e nenhum acesso perigoso.
Resposta rápida: para criar um servidor MCP, escolha um SDK oficial, defina quais ferramentas o modelo podera chamar, implemente funções pequenas, rode o servidor localmente via stdio e conecte no Claude Code com claude mcp add. Depois teste leitura antes de escrita, coloque tokens em variaveis de ambiente e documente exatamente o que cada tool faz.
Este tutorial usa Python porque e rápido para prototipar e o SDK oficial do MCP tem suporte a servidores, clientes, tools, resources, prompts e transportes como stdio e Streamable HTTP.
O que um servidor MCP realmente entrega
Um servidor MCP pode expor três tipos principais de capacidade:
| Capacidade | O que e | Exemplo |
|---|---|---|
| Tool | Ação que o modelo pode chamar | Calcular comissao, buscar post, rodar QA |
| Resource | Dado que o modelo pode ler | Arquivo, registro, página, configuração |
| Prompt | Template reutilizavel | Briefing padrão para artigo, checklist de publicacao |
Para um primeiro servidor, comece com tools. Resources e prompts ficam para quando o padrão estiver claro.
Ideia do exemplo: ferramentas pequenas para um blog
Vamos imaginar um servidor chamado vini-tools, com duas tools:
calcular_comissao: calcula comissao liquida de afiliado.validar_slug: confere se um slug esta no formato esperado.
Não e um exemplo aleatorio. Tools assim podem virar pecas de operacao real: calculadoras, validadores, checklists, preparadores de payload e QA.
Estrutura mínima do projeto
Uma estrutura simples:
“text mcp-demo/ server.py README.md .env.example “
Se você usa ambiente virtual:
“bash python -m venv .venv .\.venv\Scripts\activate pip install mcp “
Em muitos projetos modernos, uv também funciona bem:
“bash uv init mcp-demo uv add mcp “
O ponto importante e simples: use um ambiente controlado. Não dependa do Python global da maquina se esse servidor vai virar ferramenta de trabalho.
Servidor MCP simples em Python
Exemplo de server.py:
“`python from mcp.server.fastmcp import FastMCP
mcp = FastMCP("vini-tools")
@mcp.tool() def calcular_comissao(preço: float, percentual: float, taxa_fixa: float = 0) -> dict: """Calcula a comissao bruta e liquida de uma venda.""" comissao_bruta = preço * (percentual / 100) comissao_liquida = max(comissao_bruta – taxa_fixa, 0) return { "preço": round(preço, 2), "percentual": percentual, "taxa_fixa": round(taxa_fixa, 2), "comissao_bruta": round(comissao_bruta, 2), "comissao_liquida": round(comissao_liquida, 2), }
@mcp.tool() def validar_slug(slug: str) -> dict: """Valida um slug simples para publicacao em blog.""" permitido = slug == slug.lower() and " " not in slug and "/" not in slug return { "slug": slug, "valido": permitido, "motivo": "ok" if permitido else "use minusculas, hifens e sem barras", }
if __name__ == "__main__": mcp.run() “`
Esse servidor ja ensina o essencial:
- Cada tool tem nome claro.
- A docstring explica a intencao.
- A entrada e pequena.
- A saida e JSON-like e previsivel.
- Não existe escrita em arquivo, banco ou API externa.
Conectar no Claude Code
Com o arquivo pronto, conecte via stdio:
“bash claude mcp add vini-tools -- python C:\caminho\para\mcp-demo\server.py “
Se você usa venv no Windows, prefira apontar direto para o Python da venv:
“bash claude mcp add vini-tools -- C:\caminho\para\mcp-demo\.venv\Scripts\python.exe C:\caminho\para\mcp-demo\server.py “
Depois abra:
“text /mcp “
Confirme se vini-tools aparece e se as tools foram detectadas.
Primeiro teste seguro
Peca algo pequeno:
“text Use o MCP vini-tools para calcular a comissao de uma venda de R$ 197 com 50% de comissao e R$ 2,50 de taxa fixa. “
Resultado esperado:
“json { "preco": 197.0, "percentual": 50, "taxa_fixa": 2.5, "comissao_bruta": 98.5, "comissao_liquida": 96.0 } “
Se isso funcionar, você tem o ciclo básico:
- Tool implementada.
- Servidor rodando.
- Cliente MCP conectado.
- Modelo chamando a ferramenta.
- Resultado voltando em formato estruturado.
Como transformar o exemplo em algo realmente util
Depois do MVP, evolua por dor real:
| Dor | Tool possível |
|---|---|
| Fonte solta não vira link clicavel | validar_fontes_markdown |
| Artigo novo sai sem FAQPage | checar_faq_schema |
| Capa some no card do blog | validar_capa_post |
| Slug fica inconsistente | normalizar_slug |
| Briefing fica incompleto | gerar_checklist_artigo |
| Linkagem interna demora | sugerir_links_internos |
Esse e o jeito certo de criar MCP: uma tool para uma friccao concreta.
Boas praticas de design de tools
Uma boa tool MCP deve ser chata no melhor sentido.
Ela deve:
- Fazer uma coisa.
- Ter nome especifico.
- Receber poucos parametros.
- Retornar estrutura previsivel.
- Falhar com mensagem clara.
- Ter modo dry-run quando escreve algo.
- Nunca depender de "interprete esse texto gigante" quando um campo estruturado resolve.
Evite tools como:
“text fazer_tudo_no_wordpress “
Prefira:
“text validar_post_publico enviar_indexnow atualizar_meta_rankmath criar_backup_post “
Granularidade boa deixa o agente mais confiavel.
Quando usar resource em vez de tool
Use resource quando a IA so precisa ler algo.
Exemplos:
- Lista de slugs publicados.
- Configuração editorial.
- Checklist padrão.
- Mapa de categorias.
- Relatório de status.
Se não precisa executar uma ação, não exponha como tool. Quanto menos a ferramenta puder alterar, menor o risco.
Quando usar Streamable HTTP
Stdio e ótimo para local. HTTP faz sentido quando:
- Mais de uma pessoa ou maquina precisa usar.
- O servidor fica em ambiente próprio.
- Você quer logs centralizados.
- Existe autenticacao controlada.
- A tool sera chamada por diferentes clientes MCP.
Para prototipo local, stdio. Para operacao compartilhada, HTTP.
Seguranca para servidor MCP próprio
Se a tool escreve, publique ou chama API externa, trate como producao.
Checklist mínimo:
| Item | Regra |
|---|---|
| Credenciais | Variaveis de ambiente |
| Escrita | Dry-run primeiro |
| Domínio | Allowlist |
| Logs | Entrada, saida, erro e timestamp |
| Permissao | Menor privilegio possível |
| Erro | Mensagem clara, sem vazar segredo |
| Deploy | Separar teste e producao |
O maior ganho de um servidor MCP próprio não e impressionar. E reduzir erro repetitivo em processos que ja importam.
Perguntas frequentes
Preciso saber muito backend para criar um servidor MCP?
Não para o primeiro servidor. Se você consegue escrever funções simples em Python e entende entrada/saida, ja da para criar tools locais uteis.
Qual SDK usar: Python ou TypeScript?
Use o que combina com seu projeto. Python e excelente para scripts, dados e automacao local. TypeScript combina bem com stacks Node, apps web e pacotes npm.
Posso criar MCP para publicar no WordPress?
Pode, mas comece com leitura e validacao. Para escrita em WordPress, use dry-run, backup, allowlist e credenciais com permissao mínima.
Um servidor MCP local precisa ir para o Git?
So quando estiver estavel e não tiver segredo. Experimentos podem ficar locais até virarem padrão do projeto.
Como sei se vale criar uma tool MCP?
Se você repete a tarefa, explica sempre do mesmo jeito e o erro custa tempo ou dinheiro, provavelmente vale transformar em tool.
Fontes e metodologia
Este tutorial foi escrito em 17/07/2026, usando documentacao oficial do MCP e fluxo de teste local com Claude Code.