Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Construa e Implemente o Seu Próprio Servidor MCP

Aula 13 de 14 Atualizada a 2 de novembro de 2026 Intermediario
Nesta página
  1. Da Ideia ao Servidor de Produção
  2. Criação Local de um Servidor MCP
  3. Testes Locais
  4. Opções de Implementação
  5. Servidores de Ferramenta Múltipla vs. Única
  6. Gestão de Variáveis de Ambiente
  7. Pontos-chave

Atualização de 2 de novembro de 2026 — O Le Chat é agora o Vibe. Desde 28 de maio de 2026, o Le Chat foi rebatizado como Vibe (ainda em chat.mistral.ai): um único agente para trabalho e código, mantendo as suas conversas, definições e subscrições. A experiência legada do Le Chat permanece acessível no modo Chat; no modo Work, os agentes tornaram-se competências (invocadas com @), as memórias servem como base de conhecimento e a pesquisa profunda é agora a competência Deep Research. Os planos passaram a designar-se Mistral Free, Pro, Team e Enterprise. Esta lição utiliza o nome Vibe; note que alguns menus aqui descritos podem ter alterado de nome ou localização.

Da Ideia ao Servidor de Produção

Já sabe como utilizar conectores existentes e adicionar personalizados. Chegou o momento de dar o passo final: escrever o seu próprio servidor MCP e implementá-lo para utilização no Vibe. Vamos percorrer todo o caminho aqui, desde o primeiro ficheiro Python na sua máquina até à hospedagem em produção, abordando as escolhas de design que separam um servidor utilizável de um que o modelo nunca invoca corretamente.

Criação Local de um Servidor MCP

A biblioteca FastMCP (pip install fastmcp, versão 4 em novembro de 2026), um framework independente do SDK oficial mcp, reduz a criação de servidores a alguns decoradores:

from fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool()
def greet(name: str) -> str:
    """Greets a person by name.

    Args:
        name: The first name of the person to greet.

    Returns:
        A personalized greeting message.
    """
    return f"Hello {name}! Welcome to our platform."

Tudo depende destas poucas linhas. O decorador @mcp.tool() regista a função como uma ferramenta MCP. A docstring torna-se na descrição que o modelo vê ao decidir se deve invocar a ferramenta — por isso, não é um comentário para os seus colegas, mas um elemento funcional. A tipagem dos parâmetros (name: str) e do retorno (-> str) informa o modelo sobre os tipos esperados, e o nome da função deve ser claro e descritivo. A alternativa oficial é o SDK MCP da Anthropic, disponível em Python e TypeScript: oferece mais controlo, ao custo de uma configuração ligeiramente mais pesada.

Uma vez que o modelo vê apenas a descrição textual da sua ferramenta, escreva-a como um manual de utilizador completo:

@mcp.tool()
def search_products(
    query: str,
    category: str = "all",
    max_results: int = 10
) -> str:
    """Searches the product catalog.

    Use this tool when the user looks for a product
    by name, SKU, or category.

    Args:
        query: Search terms (product name, SKU, keywords).
        category: Filter category. Possible values: 'all',
                  'electronics', 'clothing', 'food'. Default: 'all'.
        max_results: Maximum number of results to return (1-50).

    Returns:
        List of products with name, price, availability, and SKU.
    """

Observe o que esta docstring acrescenta e que faltava na anterior: a condição de utilização, os valores possíveis para category e os limites para max_results. Mais duas regras completam o exercício. Os nomes devem ser explícitos — prefira search_products em vez de search, create_invoice em vez de create, get_user_orders em vez de get_data. E os retornos devem ser legíveis: devolva texto compreensível em vez de IDs brutos, caso contrário o modelo não conseguirá utilizá-los para formular uma resposta natural.

Testes Locais

Primeiro, inicie o servidor, que corre numa porta local, por defeito localhost:8000:

python server.py

Depois, exponha-o para que o Vibe possa aceder-lhe:

ngrok http 8000

O ngrok fornece um URL público, por exemplo https://abc123.ngrok.io, que utilizará como URL do conector no Vibe — lembre-se de acrescentar /mcp para obter o endpoint completo. Antes de avançar para o Vibe, valide o servidor com o MCP Inspector:

npx @modelcontextprotocol/inspector

Ligue-se ao seu servidor local, liste as ferramentas, teste-as individualmente e verifique os retornos. Isto indicar-lhe-á se eventuais problemas provêm do seu código ou da forma como o modelo interpreta as suas descrições.

Opções de Implementação

Assim que o seu servidor estiver pronto, a hospedagem depende sobretudo das suas restrições. O Hugging Face Spaces é a opção gratuita recomendada pela equipa da Mistral AI: são máquinas virtuais que hospedam aplicações web, totalmente gratuitas enquanto não necessitar de uma GPU. Pode configurar o seu servidor MCP lá com FastAPI e implementar vários servidores no mesmo Space, cada um com o seu próprio endpoint — /api1/mcp, /api2/mcp — que o Vibe adicionará como conectores separados. Um bónus adicional: nada o impede de adicionar um frontend ao Space para visualizar a atividade do seu servidor.

O Prefect Horizon (anteriormente FastMCP Cloud), a plataforma da equipa FastMCP, importa diretamente um repositório GitHub contendo um servidor FastMCP: seleciona o repositório em horizon.prefect.io, a plataforma compila-o e publica um URL autenticado; existe um nível gratuito para projetos pessoais. Para servidores leves sem dependências pesadas, o Cloudflare Workers oferece uma implementação na borda rápida e de baixo custo. Por fim, os fornecedores tradicionais permanecem perfeitamente viáveis para equipas já equipadas: AWS (Lambda, ECS), Google Cloud (Cloud Run, Cloud Functions) ou Azure (Functions, Container Apps).

Servidores de Ferramenta Múltipla vs. Única

Um reflexo comum é dividir as ferramentas de forma muito fina. A experiência aponta no sentido oposto: um hackathon MCP organizado pela Mistral mostrou que as equipas com melhor desempenho conceberam ferramentas de alto nível correspondentes a fluxos de trabalho completos. Expuseram book_restaurant em vez de list_restaurants + check_availability + make_reservation, ou deploy_application em vez de build + test + push + deploy. O modelo tem menos hipóteses de errar a sequência e a latência cumulativa diminui correspondentemente.

A granularidade ainda faz sentido em três situações: quando está a criar um servidor MCP genérico utilizado por diferentes equipas, quando as etapas do fluxo de trabalho podem servir independentemente umas das outras e quando necessita de flexibilidade na ordem das operações.

Gestão de Variáveis de Ambiente

Os seus servidores necessitarão frequentemente de chaves de API, credenciais de bases de dados ou outros segredos. Guarde-os sistematicamente em variáveis de ambiente, nunca no código. Tenha especialmente em mente que um servidor MCP público sem autenticação permite que qualquer pessoa consuma as suas chaves de API: proteja-o com um token ou OAuth assim que invocar um serviço pago. No Hugging Face Spaces, os Secrets do Space foram concebidos exatamente para este fim.

Pontos-chave

  • O FastMCP é a forma mais simples de criar um servidor MCP em Python
  • Apolimente as descrições, os nomes e a tipagem das suas ferramentas
  • Teste localmente primeiro com o ngrok e o MCP Inspector antes de implementar
  • O Hugging Face Spaces oferece uma hospedagem gratuita ideal para servidores MCP
  • Prefira ferramentas do tipo fluxo de trabalho em vez de excessivamente granulares
  • Proteja os seus segredos e considere a autenticação para os seus servidores