FastMCP ou SDK MCP: qual framework Python usar?

Você cola from mcp.server.fastmcp import FastMCP de um tutorial em um projeto novo, executa, e o Python responde com um ModuleNotFoundError. Nada está errado com a sua configuração. O SDK oficial renomeou essa classe, o projeto FastMCP independente seguiu em frente por conta própria, e as duas bibliotecas agora compartilham um nome, uma camada de protocolo e um bom número de desenvolvedores confusos.

Aqui vai a resposta rápida. Em outubro de 2026, o pacote oficial mcp está na versão 2.3.0 e o pacote fastmcp independente na versão 4.0.11. Escolha o FastMCP quando quiser composição de servidores, proxy, importação de OpenAPI, provedores de autenticação prontos e um cliente de teste em processo. Escolha o SDK oficial de MCP quando quiser a menor árvore de dependências, controle direto sobre as primitivas do protocolo e nenhum framework extra entre o seu código e a especificação.

💡 Veredito rápido: se você está criando um servidor do Model Context Protocol que usuários reais vão acessar e não tem certeza, comece com o FastMCP. Para um servidor simples, migrar depois para o SDK oficial é uma edição de cinco minutos. Fazer o caminho inverso significa reconstruir recursos que o FastMCP já entregava de graça.

Por que duas bibliotecas compartilham um nome

Como o FastMCP acabou no SDK

Jeremiah Lowin criou o FastMCP para que escrever um servidor MCP parecesse escrever uma função Python comum. Essa API de alto nível foi boa o bastante para que o SDK Python oficial da Anthropic a incorporasse em 2024 como FastMCP 1.0, disponível em mcp.server.fastmcp. O projeto independente nunca parou. Continuou sendo publicado com o próprio nome de pacote, chegou à versão 3.0 GA em 18 de fevereiro de 2026 e saiu de uma conta pessoal do GitHub para o repositório PrefectHQ/fastmcp quando a Prefect o adotou como infraestrutura central.

Hoje ele é mantido por Jeremiah Lowin e Nate Nowack sob a licença Apache-2.0. O projeto afirma que é usado por cerca de 70% dos servidores MCP em todas as linguagens, um número autodeclarado que pede cautela.

O que mudou no SDK v2

O SDK v2 oficializou a divisão. A classe FastMCP incluída agora é MCPServer, e o caminho de importação antigo foi removido por completo:

# SDK v1 (bundled FastMCP, gone in v2)
from mcp.server.fastmcp import FastMCP

# SDK v2
from mcp.server import MCPServer

# Standalone FastMCP
from fastmcp import FastMCP

Copiar prompt

Se você ainda precisa do comportamento antigo, a linha v1 fica em modo de manutenção. Instale-a com uv add "mcp[cli]<2".

Você não está escolhendo entre duas implementações rivais do protocolo. O FastMCP 4 se apoia na mesma camada de protocolo do SDK v2, então a pergunta real é quanto framework você quer colocar por cima dela.

Lado a lado: a comparação rápida

Veja como os dois se saem nos pontos que decidem a maioria dos projetos:

Os números de tamanho de instalação vêm de um teste lado a lado publicado em 5 de outubro de 2026, então seus números vão variar conforme a plataforma e os extras.

Servidor mínimo nas duas bibliotecas

O código do primeiro dia é quase idêntico. Nas duas bibliotecas, as dicas de tipo viram JSON Schema e as docstrings viram descrições de ferramentas. Aqui está a versão do SDK oficial:

from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Copiar prompt

E a versão do FastMCP:

from fastmcp import FastMCP

mcp = FastMCP("Demo")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

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

Copiar prompt

Com o extra cli do SDK, você pode testar a primeira usando mcp dev server.py. A segunda roda com um simples python server.py.

Pequenas diferenças de sintaxe que causam problemas

A maioria dos bugs de migração vem de detalhes como estes:

• Parênteses: o MCPServer do SDK exige @mcp.tool(). Um @mcp.tool sem parênteses gera um TypeError. O FastMCP aceita os dois.
• Nome do transporte: o SDK o chama de "streamable-http". O FastMCP o chama de "http".
• Configurações de transporte: no SDK v2, host e porta saíram do construtor e foram para a chamada run().
• Propriedades do contexto: ctx.mcp_server no SDK vira ctx.fastmcp no FastMCP, e ctx.log(level, data) vira ctx.log(message, level=...).

O que o SDK oficial faz melhor

Uma pegada de dependências mais leve

O pacote oficial é a instalação menor. Nas medições de outubro de 2026, mcp 2.3.0 trouxe 36 pacotes e cerca de 41 MB para o site-packages, enquanto fastmcp 4.0.11 trouxe 66 pacotes e cerca de 65 MB. Essa diferença é o preço dos extras: provedores de autenticação, ferramentas de OpenAPI, proxy e a biblioteca cliente.

Por que isso importa na prática:

• Menos pacotes para auditar quando uma equipe de segurança revisa cada dependência transitiva.
• Imagens de contêiner menores para servidores que rodam como muitas réplicas pequenas.
• Menos superfície de atualização quando surge uma vulnerabilidade em código que o seu servidor nunca usou.

O tempo de importação a frio é um argumento mais fraco. As mesmas medições variaram bastante entre execuções na mesma máquina, então não escolha uma biblioteca por causa de algumas centenas de milissegundos de inicialização.

Controle direto do protocolo

O SDK oficial mantém uma classe Server de baixo nível ao lado da MCPServer amigável. No v2, todo handler segue um único formato, async (ctx, params) -> result, sem decoradores e sem encapsulamento automático:

from mcp.server import Server, ServerRequestContext
from mcp.types import CallToolRequestParams, CallToolResult, TextContent

async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
    return CallToolResult(content=[TextContent(type="text", text="ok")])

server = Server("Bookshop", on_call_tool=call_tool)

Copiar prompt

Você escreve o tratamento de requisições por conta própria, o que significa mais código e mais poder. O SDK v2 também adiciona ferramentas no nível do protocolo, às quais você chega de forma mais direta aqui:

• Resolve e Elicit: um parâmetro de ferramenta preenchido por uma função que você escreve, invisível para o modelo, que pode parar e fazer uma pergunta ao usuário no meio da chamada.
• Client de primeira classe: from mcp import Client negocia a conexão para você, sem ClientSession aninhado e sem inicialização manual.
• OpenTelemetry integrado: toda requisição é rastreada por middleware.
• Cache de respostas: cache_hints no servidor e suporte a cache no cliente.
• Suporte a dois protocolos: uma única implantação pode atender clientes das revisões do protocolo de 2025 e de 2026.

A revisão do protocolo de 2026-07-28 elimina o handshake initialize e os IDs de sessão no Streamable HTTP, então um balanceador de carga comum pode distribuir requisições entre réplicas sem estado. As duas bibliotecas se apoiam na mesma camada de protocolo, mas é no SDK que você a configura diretamente.

O que o FastMCP acrescenta por cima

A proposta do FastMCP é simples: as coisas que você acaba escrevendo em volta de um servidor, já escritas.

Composição e proxy

O FastMCP pode montar um servidor dentro de outro, então um servidor weather e um servidor billing podem morar em módulos separados e ainda aparecer como um único endpoint com prefixos de caminho. Ele também pode fazer proxy de um servidor MCP de terceiros, o que permite envolver um servidor existente com a sua própria autenticação. O SDK oficial não tem nenhum dos dois como recurso integrado.

A versão 3.0 reconstruiu isso em torno de provedores. As ferramentas não precisam mais ficar em um único arquivo: um FileSystemProvider as encontra em um diretório e as recarrega quando mudam.

Importação de OpenAPI e provedores de autenticação

Se a sua empresa já mantém uma API REST, OpenAPIProvider transforma uma especificação OpenAPI ou um app FastAPI em ferramentas MCP sem reescrever cada endpoint à mão.

A autenticação recebe o mesmo tratamento. O FastMCP reúne os três parâmetros separados do SDK (token_verifier, auth_server_provider e auth=AuthSettings) em um único provedor auth=, com suporte nativo a JWT, OAuth, GitHub e Google. Adicionar login com GitHub vira uma escolha de configuração, e não um projeto de fim de semana. As ferramentas também podem pedir ajuda ao LLM do cliente por meio de ctx.sample().

Testes sem rede

O Client do FastMCP aceita diretamente um objeto de servidor, então o teste roda em processo, sem portas, sem subprocessos e sem timeouts instáveis:

import asyncio
from fastmcp import Client, FastMCP

mcp = FastMCP("Demo")

@mcp.tool
def add(a: int, b: int) -> int:
    return a + b

async def main():
    async with Client(mcp) as client:
        result = await client.call_tool("add", {"a": 2, "b": 3})
        print(result.data)  # 5

asyncio.run(main())

Copiar prompt

Testes em processo são uma das vantagens que as próprias notas de migração do FastMCP destacam, e isso torna simples montar uma suíte pytest rápida.

Onde cada um fica devendo

Nenhuma escolha é gratuita. As duas cobram um preço, só que mais tarde. Equipes que escolhem o FastMCP pagam com versões que mudam o tempo todo e com uma lista maior de dependências, e equipes que escolhem o SDK pagam com o código que elas mesmas precisam escrever.

O FastMCP evolui rápido

O FastMCP foi da versão 3.0 GA em fevereiro de 2026 até a 4.0.11 em outubro, então espere que versões principais cheguem depressa. Fixe o intervalo no arquivo de projeto, por exemplo fastmcp>=4,<5, e leia as notas de versão antes de cada atualização.

Ele também instala cerca de 30 pacotes a mais que o SDK. A Prefect vende uma plataforma hospedada, a Horizon, para implantação e controle de acesso. A biblioteca em si é Apache-2.0 e roda em qualquer lugar onde você consiga rodar Python.

O SDK v2 quebra código antigo

Se você está atualizando um servidor v1, reserve tempo de verdade. As notas de versão do v2 listam estas mudanças incompatíveis:

• O transporte WebSocket (mcp[ws]) foi removido.
• A API de Tasks experimental foi removida e passou para uma extensão.
• McpError agora é MCPError, e um MCPError levantado dentro de uma ferramenta vira um erro de protocolo que o modelo nunca vê.
• O parâmetro mount_path deixou de existir.
• Handlers síncronos agora rodam em uma thread de trabalho, e não no event loop.
• No Streamable HTTP, o lifespan roda uma vez na inicialização, e não uma vez por sessão.
• O cliente HTTP passou de httpx para httpx2.

Escolha o certo em minutos

Deixe de lado a busca por recursos e relacione a sua situação com esta tabela:

Imagine uma equipe de três pessoas que quer que um assistente de IA leia a API interna de pedidos. Com uma especificação OpenAPI já pronta, OpenAPIProvider elimina a maior parte do trabalho endpoint por endpoint, e o provedor auth= único cuida do login da empresa. Agora imagine uma equipe de plataforma construindo um gateway auditado que precisa passar por uma revisão rigorosa de dependências. Essa equipe escolhe o SDK e ganha os handlers de baixo nível de que precisa. Nenhuma das equipes errou. Elas partiram de restrições diferentes.

Escolha o FastMCP quando

• Você vai lançar algo em que os usuários vão fazer login.
• Você quer uma única configuração auth= em vez de três.
• Você espera crescer de um servidor para vários.
• Você prefere o decorador @mcp.tool, mais curto, e testes rápidos em processo.

Escolha o SDK oficial quando

• Você quer as menores dependências e a menor imagem.
• Você precisa tratar requisições e respostas brutas por conta própria.
• Sua equipe padroniza a implementação de referência do projeto MCP.
• Você quer OpenTelemetry e suporte a Resolve ou Elicit direto do pacote base.

Trocar de um para o outro depois

As duas bibliotecas compartilham uma camada de protocolo, então migrar entre elas é, em grande parte, mecânico. Ir do SDK para o FastMCP fica assim:

- from mcp.server import MCPServer
+ from fastmcp import FastMCP

- mcp = MCPServer("orders")
+ mcp = FastMCP("orders")

- @mcp.tool()
+ @mcp.tool

Copiar prompt

Depois, troque "streamable-http" por "http" na sua chamada run(), renomeie ctx.mcp_server para ctx.fastmcp e junte as três configurações de autenticação em um único provedor. No caminho inverso, desfaça essas edições e planeje substituir composição, proxy e importação de OpenAPI pelo seu próprio código.

Rode os testes após cada etapa. Se você os escreveu com um cliente em processo, a verificação completa leva segundos.

Crie o seu com a Picasso IA

Um servidor MCP só é tão útil quanto aquilo que fica por trás das suas ferramentas. A Picasso IA oferece um conector MCP e uma API para desenvolvedores para geração de imagens, edição de imagens e geração de vídeo, então um cliente como o Claude Desktop pode criar visuais por meio de ferramentas que você nunca precisou construir. Esses trabalhos são assíncronos: você envia um, depois consulta o resultado. Esse formato de enviar e depois consultar também é um padrão útil para os seus próprios servidores, com uma ferramenta que devolve um ID de job e uma segunda ferramenta que verifica o status.

Rascunhe o seu servidor na PicassoIA

Você pode pedir a um LLM o primeiro rascunho de qualquer uma das versões. Aqui está o caminho rápido com o Claude Sonnet 5, um modelo criado para tarefas de programação:

1. Abra a página do Claude Sonnet 5 na PicassoIA.
2. Preencha o campo obrigatório Prompt, por exemplo: "Escreva um servidor MCP em Python usando FastMCP com duas ferramentas, uma que soma números e outra que busca um resumo do clima, além de um arquivo pytest usando o cliente em processo."
3. Defina o effort: deixe em low para edições rápidas, ou aumente para um bug complicado que envolva vários arquivos.
4. Mantenha max tokens no padrão de 8.192 para um arquivo completo de servidor, e use o system prompt para fixar um estilo de código de uma vez só.
5. Anexe uma imagem, se tiver uma, como a captura de tela de um erro, depois gere e cole o código no seu projeto.

Peça as duas versões em uma única requisição e compare as diferenças você mesmo. Se quiser uma segunda opinião sobre o código, o GPT 5.6 Sol foi criado para tarefas complexas de programação e serve bem como revisor.

Quando o seu servidor estiver rodando, dê a ele algo divertido para fazer. Abra a Picasso IA, teste os modelos de imagem e vídeo e veja o que alguns prompts bem escritos produzem. Depois, conecte a sua ferramenta favorita ao seu próprio servidor MCP e deixe o seu próximo projeto criar os próprios visuais. A sua primeira imagem está a um prompt de distância.