Publicado originalmente em claudeguide.io/mcp-server-fastapi-python

Construa um Servidor MCP em Python com FastAPI: Ferramentas, Recursos, Autenticação (2026)

Servidores MCP expõem ferramentas (funções chamáveis) e recursos (contexto legível) para Claude — a pilha mais limpa de 2026 é o SDK oficial mcp Python em cima do FastAPI em ~50 linhas de código. Você obtém transporte HTTP em streaming, esquemas de ferramentas tipados com Pydantic, autenticação por token portador e um único aplicativo ASGI que você pode enviar para Fly.io, Render ou um Mac mini. Este guia percorre todo o caminho — de pip install mcp até um servidor de produção conectado ao Claude Code via claude mcp add — com código funcional para ferramentas, recursos em streaming e autenticação estilo OAuth. Testado contra a especificação MCP 2025-06-18 e mcp-python-sdk v1.x.

O que é MCP e quando você precisa de um servidor personalizado?

O Protocolo de Contexto do Modelo é um contrato JSON-RPC que os clientes Claude (Claude Code, claude.ai desktop, o harness da API) falam com programas externos. O programa anuncia ferramentas e recursos; o cliente roteia a intenção do usuário para essas ferramentas. Você precisa de um servidor MCP personalizado quando a integração que você deseja não está no registro público — bancos de dados internos, APIs proprietárias, fluxos de trabalho personalizados sobre seu próprio sistema de arquivos. Se um MCP de fornecedor existir (GitHub, Linear, Stripe, Postgres), use isso primeiro; construa apenas o que estiver faltando.

Escolha da pilha: mcp SDK vs FastAPI puro vs apenas HTTPX

Três pilhas plausíveis, escolhidas em ordem de saída:

• mcp SDK + FastAPI (recomendado). O FastMCP do SDK envolve geração de esquema, negociação de transporte (stdio + HTTP em streaming) e estruturação JSON-RPC. Montá-lo dentro do FastAPI lhe dá middleware, coexistência OpenAPI e implantações ASGI.
• FastAPI puro, criando JSON-RPC manualmente. Faça isso apenas se você estiver bifurcando o protocolo — a especificação está mudando e você passará uma semana se atualizando a cada lançamento.
• Wrappers de cliente apenas HTTPX não são servidores; eles pertencem dentro de uma ferramenta, não como um substituto.

Escolha FastMCP. A saída é sempre "adicione uma rota FastAPI simples ao lado" — ambos podem ser montados no mesmo trabalhador Uvicorn.

Servidor mínimo funcional

Instale o SDK e o FastAPI:

pip install "mcp[cli]

## Recurso em streaming: uma lista de arquivos de repositório do GitHub

Recursos são contexto somente leitura que Claude pode puxar sem invocar uma ferramenta. Streaming é importante quando o payload é grande — Claude pode começar a raciocinar antes que o corpo termine:

python

resources/repo.py

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("acme-tools")

@mcp.resource("repo://{owner}/{name}/tree")
async def repo_tree(owner: str, name: str) -

Perguntas Frequentes

Transporte Stdio ou HTTP?

Stdio é adequado para um servidor que roda como um subprocesso de um cliente (Claude Desktop lançando um script Python local). HTTP — especificamente streamable-http — é adequado para qualquer coisa multiusuário, qualquer coisa implantada e qualquer coisa que você queira testar com mcp-inspector pela rede. Se estiver em dúvida, envie HTTP; você sempre pode envolver stdio mais tarde.

Como faço para autenticar usuários?

Tokens portadores para contas de serviço e CI. OAuth (registro dinâmico de cliente RFC 7591, conforme perfilado na especificação MCP) para usuários finais — authlib mais os auxiliares de autenticação do SDK lidam com registro, atualização e escopo. Não invente um esquema de cabeçalho personalizado; os clientes não o entenderão.

Os servidores MCP podem chamar APIs externas?

Sim — essa é a forma mais comum. Uma ferramenta é apenas uma função Python; chame qualquer cliente REST/GraphQL/banco de dados que você quiser dentro dela. Mantenha as chamadas de rede assíncronas, limite-as agressivamente (10–30s) e apresente erros upstream como ToolError com o código de status upstream na mensagem.

Qual é o limite de taxa?

Não há limite de taxa em nível de protocolo — você define. Os clientes Claude respeitam os 429s do lado do servidor, então retorne-os honestamente: um cabeçalho Retry-After em uma starlette.responses.Response com status 429 é suficiente. Para cotas por ferramenta, controle com asyncio.Semaphore mais um balde de token (por exemplo, aiolimiter).

Como faço para versionar meu servidor?

Duas camadas. O argumento version para FastMCP("name", version="1.4.0") é anunciado na negociação de inicialização — aumente em mudanças de formato de ferramenta. Separadamente, implemente caminhos de URL (/mcp/v1, /mcp/v2) quando você fizer mudanças de esquema que quebram; deixe os clientes antigos permanecerem na v1 enquanto os novos adotam a v2. Nunca mude silenciosamente o esquema de argumentos de uma ferramenta no lugar.

Para onde ir a seguir

• Melhores práticas Claude MCP — padrões para design de ferramentas, orçamento de prompts e observabilidade
• Claude Code MCP (trilha coreana) — mesmo material, mergulho profundo em coreano
• Tratamento de erros da API Claude — transforme falhas upstream em erros de ferramenta que Claude pode recuperar

Um servidor MCP funcional é um arquivo de 50 linhas. Um servidor MCP de produção é as mesmas 50 linhas mais autenticação, correlação de erros, higiene assíncrona e uma URL versionada — nada disso é difícil, mas tudo isso precisa estar lá no primeiro dia. Comece com FastMCP, envie o caminho do portador primeiro, adicione OAuth quando usuários reais chegarem e trate as descrições das ferramentas como a superfície de engenharia de prompt de maior alavancagem em sua pilha.