Implantando um Servidor MCP ao lado da sua API

TLDR; Ferramentas MCP e APIs REST atendem consumidores fundamentalmente diferentes — humanos navegam na descoberta, agentes precisam de capacidades curadas. Em vez de implantar um serviço MCP separado ou converter automaticamente sua API existente, você pode montar um servidor MCP diretamente ao lado da sua aplicação FastAPI usando FastMCP 3.x. Ambas as interfaces compartilham os mesmos serviços, banco de dados e autenticação, mas cada uma é projetada para seu próprio consumidor. Este artigo cobre a filosofia de design, arquitetura e desafios de engenharia de enviar esse padrão de interface dupla.

Introdução

O MCP (Model Context Protocol) é um padrão aberto que define como sistemas de IA interagem com ferramentas externas, fontes de dados e aplicações. Em vez de construir integrações sob medida para cada par modelo-serviço, o MCP fornece um único protocolo que qualquer agente de IA pode falar. Um servidor MCP expõe três tipos de capacidades:

• Ferramentas — Funções que o LLM chama autonomamente para tomar ação. O modelo decide quando e como invocá-las com base no contexto da conversa.
• Recursos — Dados estruturados que a aplicação fornece como contexto. Estes são somente leitura e endereçados via URIs.
• Prompts — Modelos pré-construídos que orientam os usuários através de fluxos de trabalho estruturados com entradas validadas.

Desses, as ferramentas são a interface primária para fluxos de trabalho agentic — e é onde reside o desafio de design.

Implantação

Quando as equipes adotam o MCP, o instinto padrão é implantar o servidor MCP como um serviço separado ao lado da API existente. Isso espelha o padrão de microserviços: escalonamento independente, domínios de falha isolados. Mas para a maioria das aplicações, as ferramentas MCP e os endpoints REST operam nos mesmos dados, aplicam as mesmas regras de negócios e autenticam os mesmos usuários. Um serviço separado significa lógica duplicada, configuração de autenticação duplicada e infraestrutura adicional — tudo para um adaptador de protocolo. A alternativa — e o padrão que este artigo explora — é montar o servidor MCP como uma sub-aplicação dentro do seu servidor API existente. O FastMCP 3.x gera uma aplicação ASGI padrão, o que significa que se encaixa nativamente no FastAPI ou Starlette com uma única chamada mount(). O resultado:

• Interface do Consumidor de Caminho
• /api/* Clientes web/móveis, curl REST (FastAPI)
• /mcp Agentes de IA, clientes LLM MCP (FastMCP)
• /health Infraestrutura HTTP GET

Uma implantação. Um banco de dados. Um segredo de autenticação. Duas interfaces, cada uma projetada para seu consumidor.

Quando Este Padrão se Encaixa

Bom encaixe: Suas ferramentas MCP e endpoints API atendem ao mesmo domínio com os mesmos dados. Você quer um rápido time-to-market sem nova infraestrutura. Menos ideal: Você precisa de escalonamento independente para tráfego MCP intenso, ou suas ferramentas MCP integram fontes de dados que sua API não toca.

Design

APIs REST não são ferramentas MCP. A percepção fundamental, articulada bem por Jlowin (criador do FastMCP), é que APIs REST e ferramentas MCP são projetadas para consumidores com necessidades opostas: APIs REST são projetadas para desenvolvedores humanos. Elas otimizam a descobribilidade e a atomicidade. Centenas de endpoints de propósito único são uma característica, porque desenvolvedores humanos fazem a descoberta uma vez, escrevem código que encadeia chamadas atômicas e iteram de forma barata. Mais escolha é bom. Ferramentas MCP são projetadas para agentes LLM. Cada ferramenta à qual um LLM tem acesso é processada em sua janela de contexto em cada passo de raciocínio — cada nome, descrição e esquema de parâmetro. Mais ferramentas significam mais tokens, mais latência e mais oportunidades para o modelo fazer escolhas erradas. A atomicidade é um antipadrão: cada chamada de ferramenta desencadeia um ciclo completo de raciocínio que custa tempo e dinheiro. Isso cria um desajuste de design concreto:

• Dimensão REST API MCP Tool
• Público Desenvolvedor humano escrevendo código Agente LLM raciocinando em contexto
• Custo de escolha Barato — ignorado em tempo de compilação Caro — processado em cada inferência
• Custo de iteração Rápido — saltos de rede são milissegundos Lento — cada chamada é um ciclo completo de raciocínio
• Ideal de design Rico, composável, atômico Ruthlessly curated, minimal
• Modo de falha Erros 404 / 500 Ferramentas alucidadas, seleção de ferramentas erradas

Designando Ferramentas a partir de Histórias de Agentes. A abordagem certa é começar não a partir da sua especificação de API, mas a partir da história do agente: "Como um agente, dado {contexto}, eu uso {ferramentas} para alcançar {resultado}." Para uma aplicação de tarefas, a história do agente é simples: "Como um agente, dado um usuário autenticado, eu uso ferramentas de gerenciamento de tarefas para ajudar o usuário a criar, visualizar, atualizar e concluir tarefas." Isso leva a cinco ferramentas curadas — não nove endpoints REST:

• Ferramenta MCP Propósito Por que existe
• get_all_todos Visão geral de todas as tarefas O agente precisa da imagem completa para raciocinar sobre prioridades
• get_todo_by_id Inspecionar uma tarefa específica O agente precisa do estado atual antes de sugerir atualizações
• create_todo Criar uma tarefa Capacidade central para gerenciamento de tarefas
• update_todo Modificar uma tarefa Inclui conclusão — descrição da ferramenta diz ao agente para confirmar primeiro
• delete_todo Remover uma tarefa Destrutiva — descrição da ferramenta diz ao agente para confirmar primeiro

Cada ferramenta recebe uma descrição rica que instrui o LLM sobre quando e como usá-la. Por exemplo, a descrição de update_todo afirma: "Todos os campos são obrigatórios — forneça valores atuais para campos que você não deseja alterar. Use get_todo_by_id primeiro para buscar os valores atuais antes de atualizar." Esse tipo de orientação é sem sentido em REST, mas crítico para MCP.

Visão Geral da Implementação

Arquitetura github: todos A aplicação segue uma arquitetura em camadas onde os serviços e camadas de acesso a dados são compartilhados, e apenas a camada de interface difere:

┌──────────────────────┐ ┌──────────────────────┐

│ API REST (api.py) │ │ Ferramentas MCP (mcp.py) │

│ 9 endpoints │ │ 5 ferramentas │

│ FastAPI Depends() │ │ FastMCP Depends() │

└──────────┬───────────┘ └──────────┬───────────┘

│ │ └─────────┬─────────────────┘