Como Expor sua API Existente para LLMs via MCP: Um Guia Abrangente

Integrar modelos de linguagem grandes (LLMs) com sua API existente pode ser desafiador. Tradicionalmente, você precisaria de conectores personalizados ou plugins específicos de plataforma para permitir o acesso de IA ao seu serviço. O Model Context Protocol (MCP) oferece uma maneira melhor.

O que é o Model Context Protocol (MCP)?

MCP é um padrão aberto da Anthropic (agora um projeto de código aberto) que padroniza como assistentes de IA se conectam a dados externos e ferramentas. Pense no MCP como um adaptador universal—uma “porta USB-C” para aplicações de IA. Em vez de construir integrações específicas para cada modelo ou plataforma, você expõe sua API uma vez via MCP, e qualquer LLM compatível com MCP pode utilizá-la.

Principais Benefícios do MCP

• Padronização: Substitui integrações fragmentadas por um protocolo único e consistente
• Reutilização: Construa seu conector de API uma vez como um servidor MCP, e múltiplos clientes de IA podem aproveitá-lo
• Controle: O servidor MCP é executado em seu ambiente, então você pode impor segurança e gerenciar exatamente o que o modelo pode acessar

O MCP atua como um sistema de plugin universal para LLMs, fornecendo uma maneira estruturada para uma IA chamar funções ou recuperar dados de fontes externas.

Entendendo os primitivos do MCP

O MCP utiliza três conceitos principais para expor funcionalidades:

1. Recursos: São como endpoints de dados somente leitura. Um recurso é identificado por uma URI (por exemplo, todo://list) e fornece dados ao modelo. Os recursos são destinados a carregar contexto no modelo (como buscar um documento, registro de banco de dados ou lista de tarefas). São semelhantes a solicitações GET e geralmente não alteram o estado.
2. Ferramentas: São ações ou operações que o modelo pode invocar—essencialmente funções com parâmetros e valores de retorno que o LLM pode chamar. As ferramentas podem ter efeitos colaterais ou realizar cálculos. Pense nas ferramentas como “funções que a IA pode chamar”.
3. Prompts: O MCP permite definir modelos de conversação reutilizáveis ou fluxos de trabalho. Os prompts são como trechos de conversação predefinidos que o servidor pode fornecer ao cliente.

Em resumo: recursos carregam dados para o modelo, ferramentas executam ações, e prompts orientam interações.

Implementação: Guia passo a passo

Vamos percorrer a exposição de uma API REST simples para um assistente de IA usando MCP.

Passo 1: Configurar um exemplo de API REST simples

Usaremos uma API básica de lista de tarefas como nosso exemplo. Aqui está uma implementação mínima usando Flask:

from flask import Flask, request, jsonify

app = Flask(__name__)
tasks = [ {"id": 1, "title": "Sample Task", "done": False} ]

@app.route('/tasks', methods=['GET'])
def get_tasks():
    # Return the full list of tasks
    return jsonify(tasks)

@app.route('/tasks', methods=['POST'])
def create_task():
    # Add a new task from the JSON request body
    data = request.get_json()
    new_task = {
        "id": len(tasks) + 1,
        "title": data.get("title"),
        "done": False
    }
    tasks.append(new_task)
    return jsonify(new_task), 201

# Run with: flask run

Esta API tem dois endpoints:

• GET /tasks - Recupera todas as tarefas
• POST /tasks - Adiciona uma nova tarefa

Em um cenário real, isso poderia ser qualquer API existente com um backend de banco de dados.

Passo 2: Criar um servidor MCP para encapsular a API

Agora vamos criar um servidor MCP em Python que expõe nossa API de tarefas para um LLM:

Primeiro, instale o pacote MCP:

pip install "mcp[cli]"

Em seguida, crie um arquivo chamado todo_mcp_server.py:

from mcp.server.fastmcp import FastMCP
import requests  # we'll use requests to call our REST API

# Initialize an MCP server with a descriptive name
mcp = FastMCP("To-Do API MCP Server")

# Define a Resource for reading tasks (like a GET endpoint)
@mcp.resource("todo://list")
def list_tasks() -> list:
    """Fetch all to-do tasks from the API."""
    response = requests.get("http://localhost:5000/tasks")
    response.raise_for_status()
    return response.json()  # return the list of tasks

# Define a Tool for adding a new task (like a POST operation)
@mcp.tool()
def add_task(title: str) -> dict:
    """Add a new task via the API and return the created task."""
    payload = {"title": title}
    response = requests.post("http://localhost:5000/tasks", json=payload)
    response.raise_for_status()
    return response.json()  # return the new task data

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

Vamos analisar o que está acontecendo:

• Criamos uma instância FastMCP chamada "To-Do API MCP Server", que configura o servidor e registra nossas ferramentas/recursos.
• Usamos @mcp.resource("todo://list") para expor um recurso que retorna a lista de tarefas. Isso mapeia para o endpoint GET da nossa API.
• Usamos @mcp.tool() para expor uma ferramenta que adiciona uma nova tarefa. Isso mapeia para o endpoint POST da nossa API.
• As docstrings para cada função são importantes - o LLM verá essas descrições ao decidir como usar as ferramentas.
• Executamos o servidor com mcp.run(transport="stdio"), que se comunica usando entrada/saída padrão (bom para desenvolvimento local).

Neste ponto, temos um servidor MCP com duas capacidades: um recurso todo://list (para obter tarefas) e uma ferramenta add_task (para criar uma tarefa). Estes correspondem às funcionalidades da nossa API. Em efeito, encapsulamos a API REST com MCP.

Passo 3: Executar e testar o servidor MCP localmente

Antes de executar o servidor MCP, certifique-se de que sua API Flask esteja em execução (por exemplo, com flask run).

Agora inicie o servidor MCP no modo de desenvolvimento:

mcp dev ./todo_mcp_server.py

O comando mcp dev inicia um painel de desenvolvimento interativo em seu navegador. Este painel permite:

1. Ver o nome do seu servidor MCP e as ferramentas/recursos disponíveis
2. Testar o recurso todo://list - ele deve retornar a lista atual de tarefas
3. Testar a ferramenta add_task - insira um título de tarefa e execute-a
4. Verificar resultados e ver logs no painel de histórico

Este painel é inestimável para desenvolvimento e depuração. Ele usa o mesmo protocolo MCP que um cliente LLM real usaria, mas com uma interface gráfica para testes.

Passo 4: Conectar o servidor MCP a um cliente LLM

Agora vamos conectar um LLM ao vivo ao nosso servidor MCP. Vários assistentes de IA e ferramentas suportam MCP, incluindo:

Conectando com Claude desktop

O aplicativo Claude Desktop da Anthropic tem suporte integrado para servidores MCP locais. Para integrar:

mcp install ./todo_mcp_server.py

Isso registra seu servidor com o Claude. Na interface do Claude, você deve ver seu “To-Do API MCP Server” disponível. Agora, quando você tiver uma conversa com o Claude, pode:

• Perguntar: “Liste minhas tarefas pendentes” - Claude usará o recurso todo://list
• Solicitar: “Adicione um item na lista para comprar leite” - Claude usará a ferramenta add_task

O Claude lidará com a execução do servidor MCP e o roteamento de solicitações quando a IA decidir usá-lo.

Conectando com o IDE Cursor

Cursor é um editor de código com um assistente de IA que suporta MCP. Para conectar:

1. Vá para as configurações do Cursor em “Model Context Protocol”
2. Adicione seu servidor MCP fornecendo o caminho para todo_mcp_server.py
3. Especifique o transporte (stdIo)

Uma vez conectado, o Cursor detectará as ferramentas e recursos do seu servidor. Você pode então fazer perguntas ao assistente do Cursor como “Quais tarefas estão na minha lista de afazeres?” ou “Adicione ‘escrever post de blog’ às minhas tarefas.”

Notas gerais sobre clientes LLM

Os passos exatos de conexão variam por cliente:

• Para o Claude Desktop, use mcp install ou a interface do aplicativo
• Para o Cursor, configure o servidor nas configurações
• Outros ambientes podem ter abordagens diferentes

Após a conexão, teste solicitando à IA de uma maneira que incentive o uso de ferramentas. Muitos clientes MCP indicarão visualmente quando a IA usar uma ferramenta.

Nota de Segurança: Ao conectar um servidor MCP, o LLM terá acesso a tudo o que esse servidor expõe. Servidores MCP normalmente são executados localmente ou dentro de sua infraestrutura, o que é bom para segurança. Se sua API requer autenticação, você pode incluir essas credenciais no código do seu servidor MCP.

Comparando MCP com abordagens tradicionais

Vamos comparar como usar MCP para expor uma API difere de outros métodos de integração:

Chamadas diretas de API LLM (Sem MCP)

Sem MCP, você poderia:

• Usar chamadas de função ou plugins que são específicos da plataforma (vinculados à OpenAI ou a um ambiente específico)
• Incorporar detalhes da API em prompts, o que é propenso a erros - o modelo pode alucinar endpoints ou enviar formatos incorretos

GraphQL ou outras linguagens de consulta

Com GraphQL, você poderia fazer o LLM construir consultas, mas:

• O modelo ainda precisa conhecer o esquema e a sintaxe da consulta
• Você provavelmente precisaria de uma camada de integração personalizada para verificar as consultas do modelo

A vantagem do MCP

Usar MCP abstrai esses detalhes em uma interface padronizada:

• O LLM não precisa conhecer métodos HTTP ou sintaxe de consulta
• Ele consulta o servidor MCP para ferramentas e recursos disponíveis, que têm nomes e descrições legíveis por humanos
• O processo se concentra em capacidades em vez de chamadas de baixo nível
• O mesmo servidor MCP funciona para qualquer cliente que suporte o protocolo

Aqui está uma comparação detalhada:

Aspecto Integração de API Tradicional Usando Integração MCP Padronização Sem padrão unificado - cada plataforma tem seu próprio método de integração ou formato de plugin Um padrão aberto em todas as plataformas - construa uma vez, use em qualquer lugar Descoberta de Ações O LLM deve ser informado sobre quais endpoints/consultas estão disponíveis, ou eles são codificados Clientes LLM podem listar programaticamente ferramentas/recursos disponíveis de um servidor MCP Acesso a Dados Respostas da API frequentemente enviadas via prompts, atingindo limites de contexto Recursos MCP carregam dados diretamente no contexto do LLM de maneira gerenciada Esforço de Codificação Alto - chamadas HTTP personalizadas, análise e tratamento de erros para cada modelo Simplificado - o SDK MCP lida com detalhes do protocolo; você escreve funções Python Segurança e Controle O modelo pode gerar chamadas HTTP arbitrárias se não for restringido O servidor MCP atua como um guardião - você decide exatamente o que é exposto Flexibilidade Difícil de adaptar a novos LLMs ou casos de uso Muito flexível - modelos podem orquestrar múltiplas chamadas MCP; facilmente adicionar novas ferramentas

Em resumo, MCP oferece uma camada mais amigável para IA sobre sua API. Em vez de lidar com chamadas HTTP brutas, o modelo interage com ações e dados nomeados que fazem sentido em uma conversa.

Conclusão

Expor sua API REST existente para LLMs via MCP pode simplificar muito a integração. Em vez de criar conexões específicas para cada plataforma de IA, você implementa o Model Context Protocol uma vez e ganha compatibilidade com qualquer cliente que o suporte.

MCP fornece uma maneira padronizada, segura e flexível de conectar IA e seus dados. Ele transforma sua API em um componente modular que qualquer IA avançada pode usar de forma responsável e inteligente. Isso abre novas possibilidades: seu assistente baseado em LLM poderia combinar sua API com outros conectores MCP, tudo dentro do mesmo framework unificado.

Perguntas Frequentes