Um Guia para Iniciantes sobre como Usar o FastMCP

A paisagem dos Modelos de Linguagem Grandes (LLMs) está evoluindo rapidamente, passando de uma simples geração de texto para interações complexas com sistemas externos e fontes de dados. Facilitar essa interação requer uma abordagem padronizada, uma linguagem comum para os LLMs solicitarem informações e acionarem ações. É aqui que o Protocolo de Contexto de Modelo (MCP) entra, projetado como um padrão universal – muitas vezes comparado à "porta USB-C para IA" – permitindo comunicação sem costura entre LLMs e os recursos que eles precisam.

Enquanto o MCP fornece a especificação, construir servidores e clientes que aderem a ele pode envolver um código de modelo significativo e gestão de protocolo. É aqui que o FastMCP brilha. FastMCP é um framework de alto nível, Pythonic, projetado para simplificar drasticamente a criação de servidores e clientes MCP. Ele lida com as complexidades subjacentes do protocolo, permitindo que os desenvolvedores se concentrem em definir as ferramentas valiosas, recursos de dados e padrões de interação que desejam expor aos LLMs.

💡

Deseja uma ótima ferramenta de Teste de API que gera documentação de API linda?

Quer uma plataforma integrada, tudo-em-um, para sua equipe de Desenvolvimento trabalhar em conjunto com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!

botão

O que é o Protocolo de Contexto de Modelo (MCP)?

Antes de mergulhar mais fundo no FastMCP, é essencial compreender os conceitos centrais do MCP em si. O MCP define uma maneira padronizada para que aplicativos LLM (clientes) interajam com sistemas externos (servidores). Um servidor MCP pode expor vários componentes chave:

Ferramentas: Essas são essencialmente funções que um LLM pode solicitar ao servidor para executar. Pense nelas como pontos finais POST em uma API tradicional. Elas realizam ações, potencialmente interagem com outros sistemas (bancos de dados, APIs, hardware) e retornam resultados. Por exemplo, uma ferramenta poderia enviar um e-mail, consultar um banco de dados ou executar um cálculo.
Recursos: Esses expõem dados que um LLM pode ler ou recuperar. Semelhante aos pontos finais GET, os recursos fornecem informações para enriquecer o contexto do LLM. Isso poderia ser qualquer coisa, desde arquivos de configuração e perfis de usuário até fluxos de dados em tempo real.
Prompts: Estes são templates reutilizáveis para estruturar interações com o LLM. Eles ajudam a guiar a conversa e garantir saídas consistentes para tarefas específicas.
Contexto: Os servidores podem fornecer informações contextuais, incluindo instruções sobre como interagir da melhor forma com as ferramentas e recursos disponíveis.

O MCP visa criar um ecossistema robusto e seguro onde os LLMs podem acessar e utilizar capacidades externas de forma confiável.

Por que escolher o FastMCP?

Embora você possa implementar a especificação MCP diretamente usando SDKs de nível inferior, o FastMCP oferece vantagens convincentes, especialmente para desenvolvedores Python:

🚀 Desenvolvimento Rápido: Sua interface de alto nível reduz significativamente a quantidade de código necessária, acelerando o processo de desenvolvimento. Muitas vezes, definir uma ferramenta ou recurso é tão simples quanto decorar uma função Python padrão.
🍀 Simplicidade: O FastMCP abstrai os detalhes complexos da configuração do servidor, gerenciamento de protocolo, tipos de conteúdo e gerenciamento de erros, minimizando o código de modelo.
🐍 Pythonic: Projetado com as melhores práticas do Python em mente, parece natural e intuitivo para desenvolvedores familiares com a linguagem, aproveitando recursos como dicas de tipo e decoradores.
🔍 Completo: O FastMCP visa fornecer uma implementação abrangente da especificação central do MCP, garantindo compatibilidade e acesso ao potencial total do protocolo.

A versão 1 do FastMCP provou ser altamente bem-sucedida e agora está integrada ao SDK Python MCP oficial. A versão 2 se baseia nessa fundação, introduzindo recursos avançados focados em simplificar interações de servidor, como clientes flexíveis, proxy de servidor e padrões de composição.

Como instalar o FastMCP

Configurar o FastMCP em seu ambiente Python é simples. O método recomendado usa uv, um instalador e resolvedor de pacotes Python rápido.

1. Usando uv (Recomendado):

Se você está gerenciando dependências para um projeto, adicione o FastMCP usando:

uv add fastmcp

Alternativamente, instale-o diretamente em seu ambiente:

uv pip install fastmcp

2. Usando pip:

Se você prefere usar pip, pode instalar o FastMCP com:

pip install fastmcp

3. Verificando a instalação:

Após a instalação, você pode verificar se o FastMCP está corretamente instalado e verificar sua versão, junto com a versão do SDK MCP subjacente e os detalhes do seu ambiente Python, executando:

fastmcp version

Você deve ver uma saída semelhante a esta:

$ fastmcp version

Versão do FastMCP:   0.4.2.dev41+ga077727.d20250410
Versão do MCP:                                1.6.0
Versão do Python:                            3.12.2
Plataforma:            macOS-15.3.1-arm64-arm-64bit
Caminho raiz do FastMCP:            ~/Developer/fastmcp

4. Instalando para Desenvolvimento:

Se você pretende contribuir para o próprio projeto FastMCP, você vai querer configurar um ambiente de desenvolvimento:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

Isso clona o repositório, navega para dentro do diretório e usa uv sync para instalar todas as dependências necessárias, incluindo ferramentas de desenvolvimento, dentro de um ambiente virtual. Você pode então executar testes usando pytest.

Como usar o FastMCP: Criando seu Primeiro Servidor

Agora, vamos mergulhar nos aspectos práticos de usar o FastMCP.

1. Criando uma Instância Básica de Servidor:

O núcleo de qualquer aplicação FastMCP é a classe FastMCP. Você começa criando uma instância dessa classe.

Crie um arquivo chamado my_server.py:

# my_server.py
from fastmcp import FastMCP
import asyncio # Vamos precisar disso mais tarde para o cliente

# Instanciar o servidor, dando-lhe um nome
mcp = FastMCP(name="Meu Primeiro Servidor MCP")

print("Objeto de servidor FastMCP criado.")

O construtor FastMCP aceita vários argumentos úteis:

name (str, opcional): Um nome legível para humanos para seu servidor (padrão é "FastMCP"). Útil para identificação em logs ou aplicações cliente.
instructions (str, opcional): Uma descrição orientando os clientes sobre como interagir com o servidor, explicando seu propósito ou destacando funcionalidades chave.
lifespan (callable, opcional): Um gerenciador de contexto assíncrono para lidar com a lógica de inicialização e desligamento do servidor (por exemplo, inicializando conexões de banco de dados).
tags (set[str], opcional): Tags para categorizar o próprio servidor.
**settings: Você pode passar argumentos de palavra-chave correspondentes a ServerSettings (como port, host, log_level) diretamente para o construtor para configuração.

2. Adicionando Componentes:

Um servidor vazio não é muito útil. Vamos adicionar os componentes principais do MCP.

Adicionando uma Ferramenta: Ferramentas são funções expostas ao cliente. Use o decorador @mcp.tool(). O FastMCP usa dicas de tipo do Python para definir os parâmetros de entrada esperados e o tipo de retorno para o cliente.

# my_server.py (continuação)
@mcp.tool()
def greet(name: str) -> str:
    """Retorna uma saudação simples."""
    return f"Olá, {name}!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """Soma dois números juntos."""
    return a + b

print("Ferramentas 'greet' e 'add' adicionadas.")

Adicionando um Recurso: Recursos expõem dados via um URI. Use o decorador @mcp.resource(), fornecendo a string URI.

# my_server.py (continuação)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """Fornece a configuração da aplicação."""
    return APP_CONFIG

print("Recurso 'data://config' adicionado.")

Adicionando um Template de Recurso: Estes são como recursos dinâmicos onde partes do URI atuam como parâmetros.

# my_server.py (continuação)
USER_PROFILES = {
    101: {"name": "Alice", "status": "active"},
    102: {"name": "Bob", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """Recupera o perfil de um usuário pelo seu ID."""
    # O {user_id} do URI é automaticamente passado como um argumento
    return USER_PROFILES.get(user_id, {"error": "Usuário não encontrado"})

print("Template de recurso 'users://{user_id}/profile' adicionado.")

Adicionando um Prompt: Prompts definem padrões de interação reutilizáveis.

# my_server.py (continuação)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """Gera um prompt para resumir o texto fornecido."""
    return [
        {"role": "system", "content": "Você é um assistente útil especializado em sumarização."},
        {"role": "user", "content": f"Por favor, resuma o seguinte texto:\n\n{text}"}
    ]

print("Prompt 'summarize' adicionado.")

3. Testando o Servidor (Em Processo):

Antes de executar o servidor externamente, você pode testar seus componentes diretamente dentro do mesmo script Python usando o Client. Isso é útil para verificações rápidas e testes unitários.

# my_server.py (continuação)
from fastmcp import Client # Importar o cliente

async def test_server_locally():
    print("\n--- Testando Servidor Localmente ---")
    # Apontar o cliente diretamente para o objeto servidor
    client = Client(mcp)

    # Os clientes são assíncronos, então use um gerenciador de contexto assíncrono
    async with client:
        # Chamar a ferramenta 'greet'
        greet_result = await client.call_tool("greet", {"name": "Usuário FastMCP"})
        print(f"resultado greet: {greet_result}")

        # Chamar a ferramenta 'add'
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"resultado add: {add_result}")

        # Ler o recurso 'config'
        config_data = await client.read_resource("data://config")
        print(f"recurso config: {config_data}")

        # Ler um perfil de usuário usando o template
        user_profile = await client.read_resource("users://101/profile")
        print(f"Perfil do usuário 101: {user_profile}")

        # Obter a estrutura do prompt 'summarize' (não executa a chamada LLM aqui)
        prompt_messages = await client.get_prompt("summarize", {"text": "Este é algum texto."})
        print(f"Estrutura do prompt para resumir: {prompt_messages}")

# Executar a função de teste local
# asyncio.run(test_server_locally())
# Comentado por enquanto, vamos nos concentrar em executar o servidor a seguir

Observe o uso de async e await. Os clientes do FastMCP operam de forma assíncrona, exigindo uma função async e usando async with client: para gerenciar o ciclo de vida do cliente.

4. Executando o Servidor:

Para tornar seu servidor MCP acessível a clientes externos (como uma aplicação LLM), você precisa executá-lo. Existem duas formas principais:

Execução Padrão do Python (Recomendada para Compatibilidade):
Adicione o seguinte bloco if __name__ == "__main__": ao seu arquivo my_server.py. Esta é a prática padrão do Python para tornar um script executável.

# my_server.py (no final do arquivo)

if __name__ == "__main__":
    print("\n--- Iniciando Servidor FastMCP via __main__ ---")
    # Isso inicia o servidor, geralmente usando o transporte stdio por padrão
    mcp.run()

Para executar o servidor, execute o script a partir do seu terminal:

python my_server.py

Este comando inicia o servidor MCP, ouvindo conexões de clientes usando o mecanismo de transporte padrão stdio (entrada/saída padrão). Este método garante que seu servidor execute consistentemente para vários clientes que esperam executar um script Python.

Usando a CLI do FastMCP:
O FastMCP fornece uma interface de linha de comando para executar servidores, que oferece mais flexibilidade e controle, especialmente em relação às opções de transporte.

# Executar o servidor usando stdio (padrão)
fastmcp run my_server.py:mcp

# Executar o servidor usando Eventos Enviados pelo Servidor (SSE) na porta 8080
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# Executar com um nível de log diferente
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

Pontos-chave sobre a CLI:

my_server.py:mcp: Especifica o arquivo (my_server.py) e o objeto do servidor FastMCP dentro desse arquivo (mcp). Se você omitir :mcp, o FastMCP tentará encontrar automaticamente um objeto chamado mcp, app ou server.
O bloco if __name__ == "__main__": não é necessário ao usar fastmcp run; a CLI encontra e executa diretamente o objeto do servidor especificado.
--transport: Seleciona o protocolo de comunicação (stdio, sse). SSE é comum para interações baseadas na web.
--port, --host, --log-level: Configure as configurações de transporte e registro.

5. Interagindo com um Servidor em Execução (Cliente):

Uma vez que seu servidor está em execução (seja via python my_server.py ou fastmcp run), você pode criar um script de cliente separado para interagir com ele.

Crie um novo arquivo, my_client.py:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- Criando Cliente ---")

    # Opção 1: Conectar a um servidor executado via `python my_server.py` (usa stdio)
    # client = Client("my_server.py")

    # Opção 2: Conectar a um servidor executado via `fastmcp run ... --transport sse --port 8080`
    client = Client("http://localhost:8080") # Use a URL/porta correta

    print(f"Cliente configurado para conectar a: {client.target}")

    try:
        async with client:
            print("--- Cliente Conectado ---")
            # Chamar a ferramenta 'greet'
            greet_result = await client.call_tool("greet", {"name": "Cliente Remoto"})
            print(f"resultado greet: {greet_result}")

            # Ler o recurso 'config'
            config_data = await client.read_resource("data://config")
            print(f"recurso config: {config_data}")

            # Ler perfil de usuário 102
            profile_102 = await client.read_resource("users://102/profile")
            print(f"Perfil do usuário 102: {profile_102}")

    except Exception as e:
        print(f"Ocorreu um erro: {e}")
    finally:
        print("--- Interação do Cliente Concluída ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

Execute este script de cliente enquanto o servidor estiver em execução em outro terminal:

python my_client.py

O cliente se conectará ao servidor em execução (certifique-se de que o Client(...) alvo corresponda a como o servidor está sendo executado – caminho do arquivo para stdio, URL para sse), executará as chamadas de ferramenta e leituras de recurso, e imprimirá os resultados.

6. Configuração do Servidor (ServerSettings):

Você pode ajustar o comportamento do servidor usando ServerSettings. As configurações podem ser aplicadas em ordem de precedência:

Argumentos de palavra-chave durante a inicialização do FastMCP (maior precedência).
Variáveis de ambiente (prefixadas com FASTMCP_SERVER_, por exemplo, FASTMCP_SERVER_PORT=8888).
Valores carregados de um arquivo .env no diretório de trabalho.
Valores padrão (menor precedência).

Exemplo de configuração durante a inicialização:

from fastmcp import FastMCP

mcp_configurado = FastMCP(
    name="ServidorConfigurado",
    port=8080,  # Define a porta SSE padrão
    host="127.0.0.1", # Define o host SSE padrão
    log_level="DEBUG", # Define o nível de log
    on_duplicate_tools="warn" # Avisar se ferramentas com o mesmo nome forem registradas (opções: 'error', 'warn', 'ignore')
)

# Acessar configurações pela atributo .settings
print(f"Porta Configurada: {mcp_configurado.settings.port}") # Saída: 8080
print(f"Política de Ferramentas Duplicadas: {mcp_configurado.settings.on_duplicate_tools}") # Saída: warn

As principais opções de configuração incluem host, port, log_level, e políticas para lidar com nomes de componentes duplicados (on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts).

O que mais você pode fazer com FastMCP?

O FastMCP também suporta casos de uso mais avançados:

Composição: Combine vários servidores FastMCP. main.mount("sub", sub_server) cria um link ao vivo, enquanto main.import_server(sub_server) copia componentes. Isso auxilia na modularidade.
Proxy: Use FastMCP.from_client(client) para criar uma instância de servidor FastMCP que atua como um proxy para outro servidor MCP (local ou remoto). Isso é útil para fazer a ponte entre transportes (por exemplo, expondo um servidor SSE remoto via stdio local) ou adicionando um frontend unificado.

Conclusão

O FastMCP reduz significativamente a barreira de entrada para construir aplicações LLM poderosas e cientes do contexto, simplificando a implementação do Protocolo de Contexto de Modelo. Seu design Pythonic, o foco na redução de código de modelo e um conjunto abrangente de recursos fazem dele uma excelente escolha para desenvolvedores que desejam equipar LLMs com ferramentas personalizadas e acesso a dados de forma segura e eficiente.

Seguindo os passos descritos acima – instalando o FastMCP, criando uma instância de servidor, adicionando ferramentas e recursos usando decoradores simples, e executando o servidor – você pode rapidamente começar a construir suas próprias aplicações habilitadas para MCP. Se você está criando ferramentas utilitárias simples ou integrações complexas e intensivas em dados, o FastMCP fornece a fundação para interações robustas e escaláveis com LLMs.