Como criar um servidor MCP do zero

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:

mcp-demo/
  server.py
  README.md
  .env.example

Se você usa ambiente virtual:

python -m venv .venv
.\.venv\Scripts\activate
pip install mcp

Em muitos projetos modernos, uv também funciona bem:

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:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("vini-tools")


@mcp.tool()
def calcular_comissao(preco: float, percentual: float, taxa_fixa: float = 0) -> dict:
    """Calcula a comissao bruta e liquida de uma venda."""
    comissao_bruta = preco * (percentual / 100)
    comissao_liquida = max(comissao_bruta - taxa_fixa, 0)
    return {
        "preco": round(preco, 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:

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:

claude mcp add vini-tools -- C:\caminho\para\mcp-demo\.venv\Scripts\python.exe C:\caminho\para\mcp-demo\server.py

Depois abra:

/mcp

Confirme se vini-tools aparece e se as tools foram detectadas.

Primeiro teste seguro

Peca algo pequeno:

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:

{
  "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:

1. Tool implementada.
2. Servidor rodando.
3. Cliente MCP conectado.
4. Modelo chamando a ferramenta.
5. 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:

fazer_tudo_no_wordpress

Prefira:

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 automação 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.

• MCP Python SDK
• MCP quickstart resources
• Model Context Protocol specification 2025-06-18
• Claude Code MCP documentation
• Como conectar servidores MCP no Claude Code
• Melhores servidores MCP em 2026