Como criar um servidor MCP do zero com Python

Os clientes de IA, como o Claude e o Cursor, são fantásticos a escrever código e a analisar texto, mas, tal como vêm de fábrica, estão basicamente a andar às cegas. Não conseguem ver os teus dados nem usar as tuas ferramentas sem ajuda. O Model Context Protocol (MCP) é a ponte. Um servidor MCP dá a um cliente de IA novas capacidades, como fazer uma chamada a uma API ou ler um ficheiro.

Neste guia, vais criar um servidor MCP do zero em Python. Vais usar o FastMCP, o framework de Python mais comum para esta tarefa. Aprende a ligar o servidor ao Claude e ao Cursor. Depois, vais implementar o servidor num servidor ativo, para que um cliente de IA possa aceder-lhe a partir de qualquer lugar.

O código completo é curto. Consegues concluir a compilação local em cerca de 20 minutos.

O que é um servidor MCP?

O Model Context Protocol é um padrão aberto. A Anthropic lançou-o no final de 2024. Define uma forma comum para os clientes de IA comunicarem com sistemas externos.

Um servidor MCP é um pequeno programa. Fica entre um cliente de IA e um sistema que te pertence. O cliente de IA envia um pedido. O servidor faz o trabalho e devolve um resultado.

Um servidor MCP fornece ao cliente de IA três coisas:

• Ferramentas. Ações que o cliente pode executar. Por exemplo, verificar o estado de um site.
• Recursos. Dados que o cliente pode ler. Por exemplo, uma lista de ficheiros.
• Sugestões. Instruções pré-definidas que o cliente pode reutilizar.

O valor está na padronização. Escreves o servidor uma vez. Depois, qualquer cliente de IA que suporte o MCP pode usá-lo. Não precisas de escrever uma integração personalizada para cada cliente.

O que estamos a construir hoje

Para veres como tudo isto se encaixa, vamos construir um servidor «Site Health Checker». É suficientemente compacto para ser construído de uma só vez, mas abrange os três pilares da especificação MCP.

O servidor envia ao cliente de IA:

• Uma ferramenta chamada check_site. Ela mostra o código de estado HTTP e o tempo de resposta de um URL.
• Uma ferramenta «check_ssl». Mostra quantos dias faltam até o certificado SSL de um URL expirar.
• Um recurso «monitored_sites». Mostra a lista dos sites que estás a monitorizar.
• Um prompt «health_report». Pede ao cliente um breve resumo do estado de funcionamento.

No final, fazes uma pergunta ao Claude em linguagem simples. O Claude chama a tua ferramenta e dá-te uma resposta.

Pré-requisitos

Precisas destes itens antes de começares:

• Python 3.10 ou uma versão mais recente.
• O gestor de pacotes pip ou o uv. Este guia usa o uv.
• Um cliente de IA compatível com MCP. Este guia usa o Claude Desktop e o Cursor.
• Conhecimentos básicos de Python.

Para verificares a tua versão do Python, executa este comando:

bash

python3 --version

Como funciona um servidor MCP

Antes de começares a programar, conhece as suas partes. O MCP tem três partes:

1. O anfitrião e o cliente. Trata-se da aplicação de IA, como o Claude Desktop. É ela que inicia e controla a ligação.
2. O servidor. É o teu programa. É ele que fornece as ferramentas, os recursos e os prompts.
3. As mensagens. O cliente e o servidor enviam mensagens no formato JSON-RPC.

O cliente e o servidor fazem primeiro um handshake. O cliente pergunta ao servidor o que este pode fazer. O servidor responde com a sua lista de ferramentas, recursos e prompts. Depois, o cliente pode chamá-los.

O transporte é o canal pelas quais as mensagens passam. Existem dois tipos de transporte comuns:

• stdio. O cliente inicia o servidor como um processo local. Os dois programas comunicam-se através da entrada e saída padrão. Usa o stdio para desenvolvimento local.
• HTTP. O servidor funciona como um serviço web. O cliente liga-se através de uma rede. Usa o HTTP para um servidor remoto ou partilhado.

Começas com o stdio. Mais tarde, mudas para o HTTP para a implementação remota.

Cria o servidor com o FastMCP

O FastMCP faz o trabalho pesado por ti. Ele trata do protocolo, do handshake e do formato das mensagens. Tu escreves funções simples em Python. O FastMCP transforma-as em ferramentas, recursos e prompts.

Passo 1. Cria o projeto

Cria uma pasta para o projeto. Depois, entra nessa pasta.

bash

mkdir site-health-mcp
cd
site-health-mcp

Passo 2. Instalar os pacotes

Instala o FastMCP e a biblioteca HTTP.

bash

uv init
uv add fastmcp httpx

Passo 3. Cria o ficheiro do servidor

Cria um ficheiro com o nome server.py. Adiciona as linhas de importação e o objeto servidor.

python

from fastmcp import FastMCP
import httpx
import ssl
import socket
from datetime import datetime, timezone
from urllib.parse import urlparse
mcp = FastMCP("Site Health Checker")

A linha FastMCP(“Site Health Checker”) cria o servidor. O texto é o nome do servidor. O cliente de IA mostra este nome ao utilizador.

Passo 4. Adiciona a primeira ferramenta

Uma ferramenta é uma função Python com o decorador @mcp.tool. Adiciona a ferramenta check_site abaixo do objeto server.

python

@mcp.tool
def check_site(url:str) ->dict:
    """Get the HTTP status code and the response time for a URL."""
    start = datetime.now(timezone.utc)
    response = httpx.get(url, timeout=10.0, follow_redirects=True)
    elapsed = (datetime.now(timezone.utc) - start).total_seconds()
    return{
        "url": url,
        "status_code": response.status_code,
        "ok": response.is_success,
        "response_time_seconds":round(elapsed,3),
    }

Há três partes importantes nesta função:

• O decorador @mcp.tool regista a função como uma ferramenta.
• A docstring diz ao cliente de IA o que a ferramenta faz. Escreve-a com cuidado. O cliente lê-a para decidir quando usar a ferramenta.
• As indicações de tipo (url: str e -> dict) informam ao cliente a entrada e a saída. O FastMCP constrói o esquema da ferramenta a partir delas.

Passo 5. Adiciona a segunda ferramenta

Adiciona uma segunda ferramenta que verifica o certificado SSL.

python

@mcp.tool
def check_ssl(url:str) -> dict:
    
"""Get the number of days until the SSL certificate of a URL expires."""
    
hostname = urlparse(url).hostname
context = ssl.create_default_context()
with socket.create_connection((hostname,443), timeout=10.0)as
sock:
with context.wrap_socket(sock, server_hostname=hostname)as
secure_sock:
            certificate = secure_sock.getpeercert()
    expiry = datetime.strptime(certificate["notAfter"],"%b %d %H:%M:%S %Y %Z")
    days_left = (expiry - datetime.utcnow()).days
    return{
        "url": url,
        "ssl_expiry": certificate["notAfter"],
        "days_left": days_left,
    }

Esta ferramenta abre uma ligação segura ao site. Lê o certificado. Depois, devolve o número de dias que faltam até o certificado expirar.

Passo 6. Adicionar um recurso

Um recurso é um conjunto de dados de leitura apenas. O cliente de IA lê-o, mas não executa nenhuma ação. Adiciona um recurso que liste os sites monitorizados.

python

MONITORED_SITES = [
    
"https://www.cloudways.com",
"https://www.digitalocean.com",
]
@mcp.resource("sites://monitored")
def monitored_sites() ->list[str]:
    """The list of sites that you monitor."""
    return MONITORED_SITES

O decorador @mcp.resource precisa de um URI. O URI é o endereço do recurso. Neste caso, é sites://monitored. O cliente usa o URI para solicitar os dados.

Passo 7. Adiciona um prompt

Um prompt é uma instrução reutilizável. Evita que o utilizador tenha de escrever o mesmo pedido todas as vezes. Adiciona um prompt que peça um relatório de estado.

python

@mcp.prompt
def health_report(url:str) ->str:
    """Make a prompt that asks the AI client for a health report of a site."""
    return(
        f"Check the HTTP status and the SSL expiry for {url}. "
        "Then give a short health summary."
    )

Passo 8. Adiciona o comando de execução

Adiciona as últimas linhas ao ficheiro. Estas linhas iniciam o servidor.

python

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

A chamada mcp.run() inicia o servidor com o transporte stdio. Este é o transporte correto para utilização local.

Passo 9. Executa o servidor

Inicia o servidor a partir do terminal.

bash

uv run server.py

O servidor está agora à espera de um cliente. Não mostra muita coisa, porque comunica através do stdio. Isto é normal. Pára o servidor com Ctrl + C.

O teu servidor está pronto. O próximo passo é ligar um cliente de IA.

Ligar o servidor a um cliente de IA

Agora liga o servidor ao Claude Desktop e ao Cursor. O cliente de IA inicia o servidor por ti. Não precisas de iniciar o servidor manualmente.

Ligar ao Claude Desktop

O FastMCP pode criar a configuração do Claude Desktop por ti. Executa este comando:

bash

fastmcp install claude-desktop server.py

Este comando adiciona o teu servidor ao ficheiro de configuração do Claude Desktop. Se preferires editar o ficheiro manualmente, abre-o num destes locais:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adiciona o teu servidor ao ficheiro. Usa o caminho absoluto para o teu projeto.

json

{
  "mcpServers": {
    "site-health": {
      "command":"uv",
      "args": ["run","--directory",
"/absolute/path/to/site-health-mcp","server.py"]
    }
  }
}

Guarda o ficheiro. Depois, fecha e abre o Claude Desktop novamente. O Claude Desktop só lê o ficheiro quando é iniciado.

Agora testa o servidor. Digita este pedido no Claude Desktop:

text

Check the health of https://www.cloudways.com

O Claude chama a tua ferramenta check_site. Primeiro, pede a tua aprovação. Aprova a chamada. O Claude devolve o código de estado e o tempo de resposta.

Liga-te ao Cursor

O Cursor também suporta servidores MCP. Abre as definições do Cursor e procura a secção MCP. Ou edita diretamente o ficheiro de configuração em ~/.cursor/mcp.json.

Adiciona os mesmos detalhes do servidor:

json

{
  "mcpServers": {
    "site-health": {
      "command":"uv",
      "args": ["run","--directory",
"/absolute/path/to/site-health-mcp","server.py"]
    }
  }
}

Guarda o ficheiro. O Cursor carrega o servidor. Agora já podes fazer as mesmas perguntas sobre o estado do servidor ao Cursor.

Implementar o servidor MCP num anfitrião remoto

Um servidor stdio funciona no teu próprio computador. Só o teu próprio cliente de IA é que o pode utilizar. Para partilhar o servidor, implementa-o num anfitrião remoto. Assim, qualquer cliente pode aceder-lhe através da rede.

ATENÇÃO: Um servidor MCP remoto está exposto à rede. Não implementes um servidor sem autenticação para acesso público. Uma ferramenta pode executar ações reais. Protege o servidor antes de o tornares público. Lê mais no artigo «É seguro deixar a IA gerir os teus servidores?».

Passo 1. Alterar o transporte para HTTP

Altera as últimas linhas do ficheiro server.py. Usa o transporte HTTP em vez do stdio.

python

if __name__ =="__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

O valor host=”0.0.0.0″ permite que o servidor aceite ligações da rede. O valor port=8000 define a porta. O servidor passa agora a disponibilizar um ponto final HTTP. O FastMCP mostra a URL completa quando arranca.

Passo 2. Copiar os ficheiros para o servidor

Liga-te ao teu servidor remoto via SSH. Este guia usa um Droplet da DigitalOcean, porque te dá acesso root total. Podes encontrar o endereço IP no painel de controlo do Droplet.

bash

ssh your-user@your-server-ip

Copia os ficheiros do teu projeto para o host. Depois, vai para a pasta do projeto.

Passo 3. Instala os pacotes no host

Instala o uv no host, se ainda não estiver instalado. Depois, instala os pacotes do projeto.

bash

uv add fastmcp httpx

Passo 4. Manter o servidor ativo

Um comando normal pára quando fechares a sessão SSH. Um servidor de produção tem de estar sempre a funcionar. Usa o comando « systemd » para o manter ativo. O comando « systemd » inicia o servidor, reinicia-o após uma falha e volta a iniciá-lo após um reinício do sistema.

Primeiro, descobre o caminho completo para o ficheiro « uv »:

bash

which uv 

A seguir, cria um ficheiro de serviço em /etc/systemd/system/site-health.service. Usa o teu próprio nome de utilizador, o caminho do projeto e o caminho de uv.

ini
[Unit]
Description=Site Health MCP Server
After=network.target
[Service]
User=your-user
WorkingDirectory=/home/your-user/site-health-mcp
ExecStart=/home/your-user/.local/bin/uv run server.py
Restart=always
[Install]
WantedBy=multi-user.target

Depois, inicia o serviço e ativa-o no arranque:

bash
sudo systemctl daemon-reload
sudo systemctl enable site-health
sudo systemctl start site-health

Verifica se o serviço está a funcionar:

bash
sudo systemctl status site-health

Passo 5. Expõe o servidor de forma segura

O servidor funciona numa porta do anfitrião. Para uso público, coloca o servidor atrás de um proxy reverso. O proxy reverso adiciona um certificado HTTPS e um nome de domínio limpo. Aponta o domínio para a porta do servidor.

O endpoint final fica assim:

texto

https://your-domain.com/mcp

Passo 6. Liga um cliente à URL ativa

Agora liga o Cursor ao servidor ativo. Usa o campo «url» em vez de um comando local.

json

{
  "mcpServers": {
    "site-health": {
      "url":"https://your-domain.com/mcp"
    }
  }
}

Guarda o ficheiro. O Cursor liga-se ao teu servidor ativo. As ferramentas funcionam da mesma forma que antes, mas agora o servidor está a funcionar na nuvem.

Testar e depurar o servidor

O FastMCP inclui uma ferramenta de teste chamada MCP Inspector. Ela dá-te uma página web para testares o teu servidor sem precisares de um cliente AI. Executa este comando:

bash

fastmcp dev server.py

O comando abre o MCP Inspector no teu navegador. No Inspector, podes:

• Ver a lista de ferramentas, recursos e sugestões.
• Executar uma ferramenta com dados de teste.
• Ler o resultado.

Usa o Inspector para detetar problemas logo no início. É mais rápido do que um teste feito através de um cliente de IA completo.

Próximos passos

Criaste um servidor MCP funcional, ligaste-o a dois clientes de IA e implementaste-o num servidor ativo. Para avançares mais, experimenta estas tarefas:

• Adiciona autenticação. Protege o servidor remoto com um token antes de o tornares público.
• Adiciona mais ferramentas. Dá ao servidor novas funcionalidades, como uma verificação de DNS ou um relatório de utilização do disco.
• Adiciona o tratamento de erros. Mostra uma mensagem clara quando um site estiver em baixo ou um URL estiver errado.

Também podes saltar a compilação e usar um servidor MCP gerido. Para a gestão do alojamento, o Servidor MCP da Cloudways liga o teu cliente de IA à tua conta Cloudways. Podes gerir servidores e aplicações em linguagem simples, sem precisares de uma configuração personalizada. É uma boa opção quando queres o resultado, mas não a manutenção. Para veres como funciona, lê o Guia de Gestão de Agências MCP.