Como Criar um Servidor MCP: Tutorial Passo a Passo em Python e TypeScript (2026)

Consegue criar um servidor MCP que o Claude realmente chama em cerca de 15 minutos. Cronometrámo-lo no Node 20 e no Python 3.11: uma ferramenta add funcional, a correr sobre stdio, detetada pelo Claude Desktop, demorou 14 minutos da primeira vez e menos de 5 depois de se perceber a estrutura. Este tutorial constrói o mesmo servidor duas vezes, uma em Python com o FastMCP 2.x, outra em TypeScript com o @modelcontextprotocol/sdk 1.x — para que possa escolher a sua stack e copiar código real. Se quiser primeiro a arquitetura e a teoria do protocolo, o nosso guia de conceitos do Model Context Protocol tem-na; aqui apenas construímos.

Início Rápido do Servidor MCP: O Que Vai Criar

Um servidor MCP é um pequeno programa que expõe ferramentas, dados e modelos de prompt a clientes de IA como o Claude, o Cursor ou o VS Code através do Model Context Protocol. Escreve o servidor uma vez, e qualquer cliente compatível com MCP pode chamá-lo. Neste tutorial, vai criar um servidor com duas ferramentas (uma calculadora add e um auxiliar fetch_url), executá-lo localmente através de stdio, testá-lo e ligá-lo a um cliente real.

Eis tudo o que precisa antes de começar.

Ambos os caminhos produzem um servidor que se comporta de forma idêntica. Escolha a linguagem que a sua equipa já utiliza em produção. Se não tiver preferência, comece com Python, uma vez que o FastMCP torna o primeiro servidor mais curto.

O que é que um servidor MCP realmente expõe?

Antes de escrever código, é útil conhecer as três coisas que um servidor pode oferecer. Um servidor MCP expõe ferramentas (funções que o modelo pode chamar, como "pesquisar na base de dados"), recursos (dados só de leitura que o modelo pode carregar, como um ficheiro ou um registo) e prompts (modelos de prompt reutilizáveis). A maioria dos servidores que criar serão centrados em ferramentas; os recursos e os prompts são opcionais.

Servidor MCP, definido: um processo que fala o Model Context Protocol e anuncia uma lista de ferramentas, recursos e prompts que um cliente de IA pode descobrir e invocar em tempo de execução.

O cliente (o Claude Desktop, por exemplo) atua como anfitrião. Ele inicia ou liga-se ao seu servidor, pergunta "que ferramentas tens?" e depois chama-as quando o modelo decide que uma ferramenta é útil. Nunca chama o modelo a partir do interior do servidor. O fluxo corre no sentido contrário.

Essa direção é importante. O seu servidor é um fornecedor passivo. Espera que o cliente se ligue, responde ao pedido de descoberta e executa qualquer ferramenta que seja chamada. Mantenha esse modelo mental e o resto deste tutorial encaixa-se naturalmente.

Como Criar um Servidor MCP em Python (Passo a Passo)

O Python é o caminho mais rápido para ter um servidor a funcionar, porque o FastMCP trata da infraestrutura do protocolo e transforma funções simples em ferramentas com um decorador. Tudo o que se segue utiliza o SDK oficial de Python. Eis os quatro passos.

Passo 1: Configurar o projeto. Utilize o uv, que é atualmente o padrão para projetos MCP em Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Se preferir o pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Passo 2: Escrever o servidor. Crie o server.py:

from mcp.server.fastmcp import FastMCP
import httpx
# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

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

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Two things to notice. The docstring becomes the tool description the model reads, so write it like an instruction. And the type hints (a: int) become the input schema automatically, so FastMCP generates the JSON Schema for you.

Step 3: Run it. mcp.run() starts the server on stdio, the transport clients launch locally. You don't run this directly during development; the client launches it. For a quick smoke test, use the dev runner:

uv run mcp dev server.py

Passo 4: Devolver output limpo. Uma armadilha que vale a pena assinalar desde já: devolva uma string ou um valor tipado, não um dict aninhado simples que espera ver renderizado. Voltaremos ao porquê na secção de produção, mas a versão curta é que tipos de retorno ambíguos podem ser truncados silenciosamente em alguns clientes.

Isto é um servidor MCP em Python completo. Duas ferramentas, chamadas de rede reais, esquema automático. A seguir, o mesmo em TypeScript.

Como criar um servidor MCP em TypeScript (passo a passo)

O caminho em TypeScript usa diretamente o SDK oficial de TypeScript e o zod para validação de inputs. É um pouco mais verboso que o FastMCP, mas os tipos são excelentes e faz deploy de forma limpa em hosts Node.

Passo 1: Configurar o projeto.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Passo 2: Escrever o servidor. Crie o server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Passo 3: Executar. Em desenvolvimento: npx tsx server.ts. Em produção, compile com tsc e execute o .js gerado com o Node. Repare na forma do retorno: cada ferramenta devolve { content: [{ type: "text", text: ... }] }. Esse array content explícito é o equivalente em TypeScript da regra "devolver uma string limpa" do Python. O SDK quer blocos de conteúdo tipados, não objetos em bruto.

Passo 4: Validar inputs com o zod. O schema z.string().url() rejeita inputs inválidos antes de o seu handler ser executado, que é exatamente o que se quer quando um modelo está a gerar os argumentos.

As mesmas duas ferramentas, o mesmo comportamento, TypeScript idiomático. Vamos agora decidir como os clientes devem aceder ao seu servidor.

stdio vs. Streamable HTTP: Que transporte deve usar?

Os servidores MCP comunicam através de um de dois transportes. O stdio executa o servidor como um subproceso local, iniciado pelo cliente, com o qual comunica através da entrada/saída padrão. O Streamable HTTP executa o servidor como um serviço de rede ao qual os clientes se ligam por HTTP. Escolha consoante o local onde o servidor precisa de estar.

Regra geral: crie e teste em stdio e só mude para Streamable HTTP quando mais do que uma pessoa ou máquina precisar do servidor. A maioria dos servidores nunca precisa de sair do stdio. As chamadas mcp.run() e StdioServerTransport() acima já são stdio, por isso está tudo pronto para o desenvolvimento.

Como Testar o Seu Servidor MCP com o Inspector

Antes de ligar o seu servidor ao Claude, teste-o isoladamente com o MCP Inspector. É uma interface de navegador que se liga ao seu servidor, lista as suas ferramentas e permite chamá-las manualmente. Execute-o contra o seu servidor:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

O Inspector abre uma página local onde podes ver as tuas ferramentas add e fetch_url, disparar uma chamada de teste e ler a resposta em bruto. Este é, sem dúvida, o melhor hábito no desenvolvimento de MCP. Se o esquema de uma ferramenta estiver malformado ou um valor de retorno estiver errado, vais ver isso aqui em segundos, em vez de ficares a olhar para uma falha silenciosa dentro do Claude. Desta forma, apanhámos um esquema de entrada defeituoso que, de outra forma, nos teria custado uma ida e volta completa de depuração através do cliente. Testa sempre primeiro no Inspector.

Como Ligar o Seu Servidor MCP ao Claude Desktop, Claude Code e Cursor

Assim que o Inspector estiver satisfeito, aponte um cliente real para o seu servidor. Cada cliente lê um ficheiro de configuração que lhe indica como arrancar o seu servidor através de stdio.

Claude Desktop. Edite claude_desktop_config.json (no macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Reinicie o Claude Desktop e as suas ferramentas aparecem sob o ícone de conectores.

Claude Code. Adicione o servidor com um único comando a partir do seu projeto: claude mcp add demo-server -- uv run server.py. O Claude Code guarda-o na configuração do seu projeto e carrega-o no arranque. Se também usar hooks para automatizar o Claude Code, o nosso guia de hooks do Claude Code combina bem com ferramentas MCP personalizadas.

Cursor. Adicione o mesmo bloco mcpServers a .cursor/mcp.json na raiz do seu projeto. A estrutura é igual à do Claude Desktop. Para um exemplo real de um servidor MCP a correr dentro do Claude Code, veja como ligámos o Higgsfield ao Claude Code.

Use caminhos absolutos em todas as configurações. Os caminhos relativos são a razão mais comum para um servidor falhar ao arrancar.

Implementar um Servidor MCP em Produção (Autenticação e Alojamento)

Quando o seu servidor precisar de ser partilhado, migre-o de stdio para Streamable HTTP e adicione três coisas: autenticação, tratamento de erros e um alojamento.

• Autenticação. Os servidores MCP remotos devem usar OAuth 2.1 de acordo com a especificação de autorização do MCP. Para ferramentas internas, uma verificação de bearer token no endpoint HTTP é o mínimo pragmático. Nunca publique um servidor de ferramentas público e não autenticado, porque uma ferramenta que executa SQL ou acede a APIs internas é uma superfície de ataque ativa.
• Tratamento de erros. Envolva o corpo das ferramentas em try/except (ou try/catch) e devolva uma mensagem de erro tipada em vez de lançar uma exceção. O modelo lida com "a consulta falhou, eis o motivo" muito melhor do que com uma ligação interrompida.
• Alojamento. Qualquer plataforma que execute um processo Node ou Python de longa duração serve: um pequeno VPS, Fly.io, Railway ou um contentor na sua própria infraestrutura. Mantenha o processo ativo, uma vez que os arranques a frio acrescentam latência à primeira chamada de ferramenta.
• Concorrência e custos. Se as suas ferramentas chamarem um LLM ou uma API paga a jusante, coloque um gateway à frente delas. O nosso resumo de ferramentas de gateway de LLM abrange limitação de taxa e fallback, e as ferramentas de engenharia de contexto ajudam a evitar que os resultados das ferramentas sobrecarreguem a janela de contexto do modelo.

Em Python, mude a chamada de execução para mcp.run(transport="streamable-http"); em TypeScript, substitua StdioServerTransport pelo StreamableHTTPServerTransport do SDK. As definições das ferramentas não mudam nada — é precisamente esse o objetivo da abstração de transporte.

O que aprendemos ao colocar servidores MCP em produção

Construímos servidores MCP para uso interno na Techsy, e algumas lições só surgem quando o tráfego real chega. Eis o que medimos e onde fomos apanhados.

O primeiro servidor que lançámos foi uma ferramenta de consulta Postgres só de leitura, construída com FastMCP 2.x sobre o SDK Python mcp 1.x, mais tarde reescrita em @modelcontextprotocol/sdk 1.x para comparação. Numa stack de 2026 (Node 20, Python 3.11), as chamadas de ferramentas stdio locais acrescentavam aproximadamente 8 a 12 ms de sobrecarga de transporte por chamada. Assim que movemos esse mesmo servidor para Streamable HTTP num VPS, o custo por chamada subiu para 40 a 70 ms, quase inteiramente round-trip de rede em vez de custo de protocolo. O cold-start do FastMCP era de cerca de 300 ms para o processo, razão pela qual mantemos o processo de produção aquecido.

A armadilha que nos custou cerca de duas horas: uma ferramenta que devolvia um dict Python em bruto era renderizada corretamente no Inspector, mas voltava truncada dentro do Claude Desktop. Envolver o valor de retorno como uma string de texto tipada resolveu-o instantaneamente. É por isso que este tutorial devolve strings e blocos de texto content em todo o lado, em vez de objetos aninhados. O outro hábito que compensou imediatamente foi passar todos os servidores pelo npx @modelcontextprotocol/inspector antes de tocar na configuração do cliente, o que revelou um schema de input malformado na reescrita em TypeScript que, de outra forma, teria falhado silenciosamente no Cursor.

Se está a escolher que ferramentas transformar em servidores, em primeiro lugar, a nossa lista dos melhores servidores MCP em 2026 é um bom banco de ideias.

Como a Techsy Aborda o Desenvolvimento de MCP

Na Techsy, construímos servidores MCP como parte dos sistemas de agentes de IA que entregamos aos clientes, ligando agentes a bases de dados internas, CRMs e APIs através de uma camada de ferramentas tipada. A nossa abordagem consiste em começar de forma restrita (uma ferramenta bem testada por stdio), validá-la no Inspector e só depois promovê-la a um serviço HTTP autenticado quando mais do que um agente precisar dela. Combinamos servidores personalizados com o Claude Agent SDK quando a lógica do agente se torna complexa.

Esta é a versão honesta: a maioria das equipas constrói demais o seu primeiro servidor. Raramente precisas de HTTP, OAuth e uma dúzia de ferramentas no primeiro dia. Se quiseres uma segunda opinião sobre uma integração MCP, pede uma consulta gratuita e dir-te-emos se é um trabalho de uma ferramenta em stdio ou algo que precisa genuinamente de infraestrutura.

Perguntas Frequentes

Devo criar o meu servidor MCP em Python ou TypeScript?

Use aquela que a sua equipa já utiliza em produção. Python com FastMCP é o caminho mais curto para um primeiro servidor funcional, porque um decorator transforma uma função numa ferramenta. TypeScript com o SDK oficial é ligeiramente mais verboso, mas oferece tipos excelentes e faz deploy de forma limpa para hosts Node. Ambos produzem servidores que se comportam de forma idêntica para o cliente.

Preciso de um framework como o FastMCP para criar um servidor MCP?

Não, mas ajuda. O FastMCP vem incluído no SDK oficial de Python mcp e elimina a maior parte do boilerplate do protocolo. Pode usar a API Server de nível inferior para um controlo mais fino, mas para quase todos os servidores, o FastMCP (Python) ou o McpServer (TypeScript) é a ferramenta certa e com muito menos código.

Como faço debug a um servidor MCP que não está a funcionar?

Primeiro, execute-o através do MCP Inspector: npx @modelcontextprotocol/inspector seguido do seu comando de execução. O Inspector lista as suas ferramentas e permite chamá-las diretamente, para que possa confirmar que o servidor funciona antes de culpar o cliente. Se o Inspector estiver bem, mas o cliente não, verifique se a sua configuração utiliza caminhos absolutos e se reiniciou o cliente.

O FastMCP é uma parte oficial do MCP?

Sim. O FastMCP vem incluído no SDK oficial em Python do Model Context Protocol como a interface de servidor de alto nível. O decorador @mcp.tool() que utilizas é a forma recomendada de criar servidores em Python, e não um complemento de terceiros.

Qual é a diferença entre um servidor MCP local e um remoto?

Um servidor local é executado na sua máquina através de stdio, iniciado pelo cliente como um subprocesso — ideal para ferramentas pessoais e desenvolvimento. Um servidor remoto é executado como um serviço web através de Streamable HTTP e pode ser acedido por vários clientes, o que requer autenticação OAuth 2.1. Comece por construir localmente e só passe para remoto quando precisar de partilhar.

Em que linguagens posso criar um servidor MCP?

O Model Context Protocol dispõe de SDKs oficiais para Python, TypeScript, Java, Kotlin e C#, com SDKs comunitários noutras linguagens. Uma vez que o MCP é um protocolo de comunicação, qualquer linguagem que consiga ler e escrever JSON-RPC através de stdio ou HTTP pode implementar um servidor, mas os SDKs oficiais poupam-lhe esse trabalho.

Um servidor MCP funciona com o ChatGPT e o Gemini, ou apenas com o Claude?

O MCP é um padrão aberto adotado em todo o ecossistema de IA agêntica, incluindo o ChatGPT, o Gemini, o Cursor e o VS Code Copilot. Um único servidor que construa funciona com qualquer cliente compatível. Não precisa de escrever uma integração separada para cada modelo, o que é precisamente a razão de ser do protocolo.

Quanto tempo demora a construir um servidor MCP funcional?

Um primeiro servidor com uma ou duas ferramentas a correr sobre stdio demora cerca de 15 minutos depois de o runtime estar instalado. Medimos 14 minutos para um iniciante em Node 20 e menos de 5 minutos para uma reconstrução. O que realmente consome tempo é adicionar autenticação, transporte HTTP e alojamento em produção — não o servidor em si.

Sobre o Autor

Mert Batur Gurbuz é Cofundador da Techsy.io, onde a equipa desenvolve agentes de IA, sistemas de automação e pipelines de voz/SDR para clientes B2B. Estuda na University of Birmingham e escreve sobre a stack de ferramentas de LLM que a equipa da Techsy utiliza efetivamente em produção. Ligue-se no LinkedIn.

Mert Batur Gurbuz, Cofundador, Techsy.io, University of Birmingham