Você usa Claude ou ChatGPT todo dia. Manda bem — prompts, follow-ups, toda a dança. Mas toda vez que precisa de dados do CRM da empresa, do gerenciador de projetos ou do banco interno, você vira um cabo USB humano: copia da aba A do navegador, cola na aba B do chatbot, repete até a alma sair do corpo.

O que a maioria dos tutoriais não fala abertamente é o seguinte: a distância entre "IA que conhece a internet" e "IA que conhece o seu negócio" é exatamente um arquivo Python. Não é migração de plataforma. Não é contrato com fornecedor de seis dígitos. Um único arquivo com um decorator e uma docstring. O protocolo já existe, toda grande empresa de IA já adotou, e você consegue conectar tudo numa tarde. Deixa eu mostrar.

Por que as respostas óbvias não funcionam

"Só usar a API" — ótimo conselho, só que sua IA não tem mãos. Ela não consegue chamar a REST API da sua empresa (uma URL que retorna dados quando você pede educadamente) por conta própria. Você poderia colar a documentação da API no chat, mas isso devora sua janela de contexto — quanto texto a IA consegue "ver" de uma vez, a memória de trabalho dela — e você continua fazendo o trabalho braçal. Integrações estilo Zapier existem, mas são rígidas: gatilhos predefinidos, ações predefinidas e uma página de preços que faz seu financeiro chorar.

O que você realmente precisa é de uma forma de deixar sua IA descobrir e chamar suas ferramentas internas diretamente — sem você ser o intermediário.

MCP: o padrão que resolveu isso

MCP (Model Context Protocol) é um padrão universal de conexão para ferramentas de IA — pensa num USB-C, só que pra conectar IA aos seus dados. A Anthropic lançou como open-source em novembro de 2024. Até março de 2026, atingiu 97 milhões de downloads mensais do SDK. OpenAI, Google e Microsoft — todos adotaram. Em 26 de abril de 2026, mais de 17.000 servidores MCP estão indexados nos registros.

O SDK Python permite construir um servidor funcional em um único arquivo. Veja como.

Passo 1: Instale o SDK

Você precisa de Python 3.10+ e do uv (gerenciador de pacotes recomendado pela Anthropic) ou do bom e velho pip.

# Opção A: uv (recomendado)
uv init my-mcp-server && cd my-mcp-server
uv add "mcp[cli]" httpx

# Opção B: pip
pip install "mcp[cli]" httpx

httpx é uma biblioteca HTTP para Python — é o que seu servidor usa para buscar dados de APIs externas. Se seus dados estão num banco de dados, troque pelo driver do seu banco.

Passo 2: Escreva o servidor

Crie server.py. Aqui vai um servidor MCP completo que busca alertas meteorológicos do National Weather Service dos EUA — uma API real, sem chave de autenticação, perfeita pra aprender:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# FastMCP — um wrapper de alto nível que transforma
# funções Python comuns em ferramentas MCP
mcp = FastMCP("weather")

NWS_API_BASE = "https://api.weather.gov"

async def make_request(url: str) -> dict[str, Any] | None:
    headers = {
        "User-Agent": "mcp-weather-demo/1.0",
        "Accept": "application/geo+json",
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(
                url, headers=headers, timeout=30.0
            )
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get active weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    data = await make_request(
        f"{NWS_API_BASE}/alerts/active/area/{state}"
    )
    if not data or "features" not in data:
        return "No alerts found."

    alerts = []
    for feature in data["features"][:5]:
        props = feature["properties"]
        alerts.append(
            f"Event: {props.get('event', 'Unknown')}\n"
            f"Area: {props.get('areaDesc', 'Unknown')}\n"
            f"Severity: {props.get('severity', 'Unknown')}"
        )
    return "\n---\n".join(alerts) or "No active alerts."

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

Cerca de 40 linhas de código real. O decorator @mcp.tool() — um atalho Python que registra sua função como ferramenta chamável por IA — faz o trabalho pesado. O FastMCP lê seus type hints (state: str) e a docstring (a descrição entre aspas triplas) para gerar automaticamente definições de ferramentas que a IA entende.

Esse é o padrão central. Todo servidor MCP que você já viu — Slack, GitHub, Figma, todos os 17.000+ — é esse mesmo esqueleto com mais endpoints.

Passo 3: Conecte ao Claude Desktop

O Claude Desktop lê um arquivo de configuração JSON (um arquivo de configurações num formato específico) para saber quais servidores MCP iniciar. Encontre-o em:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Crie ou edite:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/caminho/absoluto/para/my-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Substitua /caminho/absoluto/para/my-mcp-server pelo caminho completo real. Caminhos relativos não funcionam — isso pega todo mundo de primeira.

Reinicie o Claude Desktop. Procure o ícone de martelo no canto inferior direito do campo de chat. Clique nele — você deve ver get_alerts listado. Se não aparecer, confira ~/Library/Logs/Claude/mcp*.log no macOS para erros.

Passo 4: Pergunte algo ao Claude

Digite: "Tem algum alerta meteorológico na Califórnia agora?"

O Claude reconhece que tem uma ferramenta get_alerts, pede sua permissão para chamá-la, acessa seu servidor e responde com dados ao vivo do NWS que ele não conseguia acessar cinco minutos atrás.

Esse é o momento "aha". Seu chatbot acabou de deixar de ser genérico.

Passo 5: Substitua a API de clima pela sua

Agora troque make_request por qualquer API que sua equipe usa — Jira, Linear, seu dashboard interno. Se tem um endpoint que retorna dados, está a uma função de distância de virar uma ferramenta de IA. O padrão é sempre:

  1. Escreva uma função async que busca dados
  2. Decore com @mcp.tool()
  3. Escreva uma docstring clara (mais sobre por que isso importa abaixo)
  4. Adicione ao seu config, reinicie

Alguns princípios de design que separam ferramentas MCP úteis das frustrantes: nomeie suas ferramentas com pares verbo-substantivo (get_alerts, search_tickets, create_issue) para que o modelo consiga inferir a intenção só pelo nome. Mantenha cada ferramenta focada em uma ação — uma função que busca, filtra e grava é três ferramentas fingindo ser uma. E para design de parâmetros, prefira argumentos tipados e explícitos ao invés de strings genéricas; state: str com uma docstring que diz "Código de estado dos EUA com duas letras" dá ao modelo informação suficiente para validar o próprio input.

Armadilhas que vão te morder

1. A descrição da sua ferramenta É o produto

Um estudo da Queen's University de fevereiro de 2026 analisou 856 ferramentas MCP em 103 servidores. Resultado: 97,1% das descrições de ferramentas tinham pelo menos um defeito de qualidade. 56% nem conseguiam articular seu propósito. Quando os pesquisadores melhoraram as descrições, as taxas de sucesso das tarefas subiram +5,85 pontos percentuais. Sua docstring não é documentação — é a interface que sua IA lê. Escreva como uma spec de produto: propósito, explicação dos parâmetros, limitações, exemplos.

2. Nunca use print() no stdout

Para servidores baseados em stdio (o que o Claude Desktop usa), escrever no stdout corrompe as mensagens JSON-RPC — o protocolo que sua IA e servidor usam para se comunicar. Seu servidor quebra silenciosamente e você passa 45 minutos olhando pro nada. Use print("debug", file=sys.stderr) ou o módulo logging do Python.

3. Segurança é responsabilidade SUA

O MCP não tem autenticação embutida para servidores locais. Tudo bem quando roda no seu laptop via stdio — é só um processo local. Mas no momento que você considerar expor via HTTP: pare. O OWASP MCP Top 10, publicado no início de 2026, existe porque pessoas pularam essa etapa. Mais de trinta CVEs foram registrados contra ferramentas MCP só em janeiro e fevereiro de 2026. O próprio FastMCP teve uma vulnerabilidade de injeção de comandos (CVE-2025-64340, divulgada no final de 2025) em todas as versões abaixo de 3.2.0.

Se seu servidor acessa APIs internas, trate-o como qualquer serviço backend: valide cada input que o modelo envia (ele vai alucinar valores de parâmetros — conte com isso), aplique o princípio de menor privilégio para que cada ferramenta só acesse os dados necessários e fixe suas dependências. Stdio local é o único padrão seguro até você resolver a autenticação direito.

4. O caminho no config precisa ser absoluto

Caminhos relativos no claude_desktop_config.json falham silenciosamente. Sem erro, sem log, só um ícone de martelo sumido e um dev lentamente perdendo a fé na humanidade. Use /Users/seunome/... no macOS — expansão de til é instável aqui.

O que você pode fazer agora

Você tem um padrão repetível. Qualquer API que sua equipe já usa — gerenciador de projetos, CRM, dashboard interno, banco de dados — está a um arquivo Python de distância de se tornar algo que sua IA pode consultar diretamente. Sem fila de espera de integração com fornecedor. Sem taxa do Zapier. Sem mais copiar e colar entre abas como se estivéssemos em 2019.

O muro entre "IA que conhece a internet" e "IA que conhece seu negócio" agora tem uma porta. Você construiu em menos linhas do que um arquivo de configuração típico.