Torne sua API REST Chamável pelo Claude: Um Primer Prático de MCP

A maioria das APIs em 2026 ainda envia os mesmos artefatos que enviou em 2016: uma especificação OpenAPI, uma página SwaggerUI, talvez uma coleção do Postman se a equipe estiver se sentindo generosa. Esses são ótimos para humanos. Eles não são suficientes para a coisa que está realmente consumindo sua API cada vez mais frequentemente — um LLM rodando dentro de um editor ou cliente de chat.

Se você quer que Claude, Cursor, Continue ou qualquer outro agente chame sua API em vez de apenas descrevê-la, você precisa de um endpoint do Protocolo de Contexto do Modelo (MCP). Este post explica o que é MCP, por que é diferente do OpenAPI e como enviar um sem reescrever seu backend.

OpenAPI diz. MCP faz.

Uma especificação OpenAPI é uma descrição: "aqui está POST /v1/customers, aqui estão seus campos, aqui estão suas respostas." Um agente que lê OpenAPI sabe sobre sua API. Ele ainda precisa traduzir esse conhecimento em uma solicitação HTTP, assinar a autenticação, analisar a resposta e lidar com erros — toda vez, em cada projeto.

MCP é diferente. Um servidor MCP expõe sua API como ferramentas chamáveis. O agente não vê "um endpoint HTTP neste URL" — ele vê create_customer(name, email, plan) como uma função que pode invocar. Autenticação, URL base, tipos de conteúdo, comportamento de repetição e análise de resposta vivem no lado do servidor. O agente apenas chama a ferramenta.

Na prática, isso significa:

• O modelo gasta menos tokens raciocinando sobre HTTP e mais tokens raciocinando sobre seu domínio.
• Segredos de autenticação permanecem no servidor MCP, não na janela de contexto do modelo.
• Você controla quais operações são expostas e com que granularidade.
• O mesmo servidor MCP funciona no Claude Desktop, Cursor, Continue, Zed e qualquer outra coisa que fale o protocolo.

O que um servidor MCP realmente expõe

Um servidor MCP tem três primitivos:

Ferramentas — funções que o agente pode chamar. Cada ferramenta tem um nome, uma descrição, um esquema JSON para seus argumentos e um manipulador que retorna um resultado. É aqui que a maior parte da superfície da sua API vive. Um GET /orders/:id se torna get_order(order_id). Um POST /orders se torna create_order(items, customer_id).

Recursos — documentos somente leitura que o agente pode puxar para o contexto sob demanda. Use-os para coisas como "a tabela de preços atual" ou "o changelog mais recente." Recursos são endereçáveis por URI e são mais baratos que ferramentas porque não requerem uma decisão de ida e volta do modelo.

Prompts — modelos de prompt pré-elaborados com argumentos nomeados. Menos comumente usados, mas úteis quando você quer enviar um fluxo de trabalho "resuma os últimos 30 dias deste cliente" em vez de uma ferramenta bruta.

Para a maioria das equipes, ferramentas e recursos representam 95% do trabalho.

As quatro decisões de design que importam

Quando você transforma uma API REST existente em um servidor MCP, quatro escolhas determinam se os agentes realmente a usarão bem.

1. Escolha a granularidade da ferramenta com cuidado. Um erro comum é expor uma ferramenta por endpoint HTTP. Isso dá ao agente 200 ferramentas e um problema de paralisia. Em vez disso, agrupe operações relacionadas em ferramentas com formato de intenção. find_customers(query) é mais útil do que list_customers + search_customers + get_customer_by_email + get_customer_by_id. O modelo é bom em escolher entre 20 ferramentas. Não é bom em escolher entre 200.

2. Escreva descrições para o modelo, não para o site de documentação. Descrições de ferramentas e parâmetros são o sinal primário que o modelo usa para decidir se e como chamar uma ferramenta. Substitua o texto de marketing ("Gerenciamento de clientes poderoso") por texto operacional ("Retorna até 25 clientes correspondentes à consulta. Use cursor da resposta anterior para paginar. Pesquisa por nome, email e external_id."). Mencione casos extremos. Mencione o que a ferramenta não faz.

3. Torne os erros legíveis. Quando uma chamada de ferramenta falha, o modelo vê o texto do erro e decide o que fazer a seguir. Um 400 com {"error": "invalid_request"} não diz nada ao agente. Um 400 com "customer_id 'cus_123' não foi encontrado — você quis dizer cus_124?" permite que o agente se autocorrija na próxima vez. Passe uma tarde trabalhando nas mensagens de erro. Isso retorna dez vezes em qualidade de repetição.

4. Decida o que não expor. Seus endpoints destrutivos (DELETE /accounts, POST /transfers) provavelmente não pertencem ao MCP ou pertencem atrás de um fluxo de confirmação. O agente tentará coisas. Assuma que qualquer ferramenta que você expor será eventualmente chamada por um agente fazendo algo que você não antecipou.

Um exemplo mínimo

Aqui está o menor servidor MCP interessante em Python — uma única ferramenta que proxy uma chamada HTTP real:

from mcp.server.fastmcp import FastMCP
import httpx, os

mcp = FastMCP("orders-api")
BASE = "https://api.example.com"
TOKEN = os.environ["ORDERS_API_TOKEN"]

@mcp.tool()
def get_order(order_id: str) -> dict:
    """Busque um pedido pelo ID.

    Args:
        order_id: O ID externo do pedido, por exemplo, "ord_abc123".

    Retorna o pedido completo, incluindo itens, status e envio.
    """
    r = httpx.get(
        f"{BASE}/v1/orders/{order_id}",
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=10.0,
    )
    if r.status_code == 404:
        re