Como Usar o Servidor FastAPI MCP: Um Guia Abrangente

O FastAPI MCP Server é uma ferramenta revolucionária que preenche a lacuna entre suas aplicações FastAPI e agentes de IA usando o Protocolo de Contexto de Modelo (MCP). Em uma era em que a integração de IA está se tornando cada vez mais importante, esta solução sem configuração permite que você exponha seus endpoints FastAPI existentes como ferramentas que podem ser descobertas e utilizadas por modelos e agentes de IA com esforço mínimo.

💡

Antes de começar a configurar o Kubernetes MCP Server, considere explorar Apidog—uma ferramenta poderosa para projetar, testar e documentar APIs. O Apidog simplifica a integração de APIs com modelos estruturados e colaboração contínua. Quando combinado com o Zapier MCP, ele aprimora a automação e o gerenciamento de APIs.

botão

Introdução ao FastAPI MCP

O Protocolo de Contexto de Modelo (MCP) é um padrão emergente que permite que modelos de IA interajam com ferramentas e recursos externos. O FastAPI MCP Server atua como uma ponte entre suas aplicações FastAPI existentes e agentes de IA compatíveis com MCP, como o Claude da Anthropic, Cursor IDE e outros, sem exigir que você reescreva sua API ou aprenda estruturas complexas novas.

O que torna o FastAPI MCP realmente notável é sua abordagem sem configuração. Ele converte automaticamente seus endpoints FastAPI existentes em ferramentas compatíveis com MCP, preservando seus esquemas de endpoint, documentação e funcionalidade. Isso significa que os agentes de IA podem descobrir e interagir com suas APIs com a configuração mínima necessária de sua parte.

Você pode encontrar o repositório do servidor FastAPI MCP em: https://github.com/tadata-org/fastapi_mcp

Começando com FastAPI MCP

Instalação

Antes de usar o FastAPI MCP, você precisará instalá-lo. Os desenvolvedores recomendam usar uv, um instalador de pacotes Python rápido, mas você também pode usar o método tradicional pip:

Usando uv:

uv add fastapi-mcp

Usando pip:

pip install fastapi-mcp

Implementação Básica

Integrar o FastAPI MCP com sua aplicação FastAPI existente não poderia ser mais simples. Aqui está a implementação mais básica:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Sua aplicação FastAPI existente
app = FastAPI()

# Crie o servidor MCP
mcp = FastApiMCP(
    app,
    name="Meu API MCP",
    description="Minha descrição da API",
    base_url="http://localhost:8000"  # Importante para roteamento de requisições
)

# Monte o servidor MCP à sua aplicação FastAPI
mcp.mount()

É isso! Com este código simples, seu servidor MCP agora está disponível em https://app.base.url/mcp. Quando um cliente compatível com MCP se conecta a este endpoint, ele descobrirá automaticamente todas as suas rotas FastAPI como ferramentas disponíveis.

Entendendo Nomes de Ferramentas e IDs de Operação MCP

Quando o FastAPI MCP expõe seus endpoints como ferramentas, ele usa o operation_id de suas rotas FastAPI como os nomes das ferramentas MCP. O FastAPI gera automaticamente esses IDs quando não fornecidos explicitamente, mas eles podem ser criptográficos e menos amigáveis ao usuário.

Compare estas duas abordagens:

# operation_id gerado automaticamente (menos amigável)
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# operation_id explícito (mais amigável)
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

No primeiro exemplo, a ferramenta pode ser chamada de algo como "read_user_users__user_id__get", enquanto o segundo exemplo seria simplesmente "get_user_info". Para melhor usabilidade, especialmente quando agentes de IA interagem com suas ferramentas, é recomendado definir explicitamente IDs de operação que sejam claros e descritivos.

Opções de Configuração Avançadas

O FastAPI MCP fornece várias opções de personalização para moldar como sua API é exposta a clientes MCP.

Personalizando a Descrição do Esquema

Você pode controlar quanta informação é incluída nas descrições das ferramentas:

mcp = FastApiMCP(
    app,
    name="Meu API MCP",
    base_url="http://localhost:8000",
    describe_all_responses=True,  # Incluir todos os possíveis esquemas de resposta
    describe_full_response_schema=True  # Incluir detalhes completos do esquema JSON
)

Filtrando Endpoints

Você pode querer controlar quais endpoints são expostos como ferramentas MCP. O FastAPI MCP oferece vários mecanismos de filtragem:

# Incluir apenas operações específicas pelo ID da operação
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# Excluir operações específicas
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# Filtrar por tags
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# Excluir por tags
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# Combinar estratégias de filtragem
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

Observe que você não pode combinar filtros de inclusão e exclusão do mesmo tipo (operações ou tags), mas pode usar filtros de operações junto com filtros de tags.

Estratégias de Deploy

O FastAPI MCP oferece flexibilidade na forma como você implementa seu servidor MCP.

Montando na Aplicação Original

A abordagem mais simples é montar o servidor MCP diretamente em sua aplicação FastAPI original, como mostrado no exemplo básico. Isso cria um endpoint em /mcp em sua aplicação existente.

Implantando como um Serviço Separado

Você também pode criar um servidor MCP a partir de uma aplicação FastAPI e montá-lo em uma aplicação diferente, permitindo que você implemente sua API e sua interface MCP separadamente:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Sua aplicação de API original
api_app = FastAPI()
# Defina seus endpoints aqui...

# Uma aplicação separada para o servidor MCP
mcp_app = FastAPI()

# Crie o servidor MCP a partir da aplicação API
mcp = FastApiMCP(
    api_app,
    base_url="http://api-host:8001"  # URL onde a aplicação API será executada
)

# Monte o servidor MCP na aplicação separada
mcp.mount(mcp_app)

# Agora execute ambas as aplicações separadamente:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

Essa separação pode ser benéfica para gerenciar recursos, segurança e escalabilidade.

Atualizando o MCP Após Adicionar Novos Endpoints

Se você adicionar endpoints à sua aplicação FastAPI após criar o servidor MCP, precisará atualizar o servidor para incluí-los:

# Configuração inicial
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()

# Depois, adicione um novo endpoint
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Olá, mundo!"}

# Atualize o servidor MCP para incluir o novo endpoint
mcp.setup_server()

Conectando-se ao Seu Servidor MCP

Uma vez que sua aplicação FastAPI com integração MCP esteja em execução, os clientes podem se conectar a ela de várias maneiras.

Usando Eventos Enviados pelo Servidor (SSE)

Muitos clientes MCP, como o Cursor IDE, suportam conexões SSE:

Execute sua aplicação
No Cursor → Configurações → MCP, use a URL do seu endpoint do servidor MCP (por exemplo, http://localhost:8000/mcp) como a URL SSE
O Cursor descobrirá automaticamente todas as ferramentas e recursos disponíveis

Usando Proxy MCP para Clientes Sem Suporte SSE

Para clientes que não suportam SSE diretamente (como o Claude Desktop):

Execute sua aplicação
Instale a ferramenta de proxy MCP: uv tool install mcp-proxy
Configure seu cliente para usar o mcp-proxy

Para o Claude Desktop no Windows, crie um arquivo de configuração (claude_desktop_config.json):

{
  "mcpServers": {
    "meu-api-mcp-proxy": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

Para macOS, você precisará especificar o caminho completo para o executável mcp-proxy, que pode ser encontrado usando which mcp-proxy.

Casos de Uso do Mundo Real

O FastAPI MCP abre inúmeras possibilidades para aplicações impulsionadas por IA:

Ferramentas de Análise de Dados: Exponha endpoints de processamento de dados que agentes de IA podem usar para analisar dados de usuários sem exigir integrações personalizadas para cada modelo de IA.
Sistemas de Gerenciamento de Conteúdo: Permita que ferramentas de IA busquem e atualizem conteúdo através da sua API CMS existente, tornando a criação e gerenciamento de conteúdo mais eficientes.
Motores de Busca Personalizados: Permita que assistentes de IA busquem em seus bancos de dados especializados ou repositórios de conteúdo através de uma interface de API simples.
Operações de Comércio Eletrônico: Deixe agentes de IA verificarem estoque, informações de produtos ou realizarem pedidos através de seus endpoints de API de e-commerce existentes.
Processamento de Documentos: Forneça ferramentas de IA com a capacidade de criar, converter ou analisar documentos usando suas capacidades de processamento de documentos no backend.

Melhores Práticas

Para aproveitar ao máximo o FastAPI MCP, considere estas melhores práticas:

Use IDs de operação explícitos: Defina IDs de operação claros e descritivos para todos os seus endpoints para torná-los mais utilizáveis por agentes de IA.
Forneça documentação abrangente: Inclua descrições detalhadas para cada endpoint e parâmetro para ajudar modelos de IA a compreender como usar suas ferramentas de forma eficaz.
Use nomes de parâmetro consistentes: Adote convenções de nomenclatura consistentes para parâmetros semelhantes em diferentes endpoints.
Considere implicações de segurança: Esteja atento a quais endpoints você expõe via MCP e implemente autenticação adequada quando necessário.
Monitore o uso: Acompanhe como agentes de IA estão utilizando suas ferramentas MCP para identificar padrões, erros ou áreas para melhoria.

Conclusão

O FastAPI MCP Server representa um avanço significativo na acessibilidade de serviços backend para agentes de IA. Ao converter automaticamente seus endpoints FastAPI existentes em ferramentas compatíveis com MCP sem configuração, ele elimina a necessidade de integrações personalizadas ou ajustes complexos no design de sua API.

À medida que o ecossistema MCP continua a crescer e mais modelos de IA adotam este padrão, ter suas APIs expostas através do FastAPI MCP posicionará seus serviços para serem prontamente acessíveis a uma ampla gama de agentes e ferramentas de IA. Se você está construindo ferramentas internas, serviços para desenvolvedores ou APIs públicas, o FastAPI MCP oferece um caminho direto para tornar seus serviços acessíveis à IA.

Seguindo as diretrizes deste artigo, você pode rapidamente integrar o FastAPI MCP em suas aplicações FastAPI existentes e começar a explorar as possibilidades de automação e interação com sua IA em seus serviços.