Noções Básicas de Servidores MCP

8 exemplos para você começar a construir servidores MCP - 5 básicos e 3 intermediários.

Pré-requisitos

Python 3.10+ e o SDK Python oficial do MCP: pip install mcp.
Ou Node.js 18+ e o SDK TypeScript oficial do MCP: npm install @modelcontextprotocol/sdk.
Um cliente para se comunicar com seu servidor. Claude Desktop, Claude Code ou um cliente personalizado construído no SDK do Agente funcionam para testes locais via stdio.
Nenhuma configuração de rede é necessária para os exemplos abaixo. Todos eles rodam via stdio, o transporte local padrão para desenvolvimento.

Exemplos Básicos

1. Esqueleto Mínimo de Servidor

O menor servidor MCP possível: crie uma instância e execute-a via stdio.

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("demo-server")
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

FastMCP é a classe de servidor de alto nível no SDK Python; ela cuida das fases de conexão e negociação de capacidade para você.
A string "demo-server" é o nome do servidor, que um cliente pode exibir ao listar servidores conectados.
mcp.run(transport="stdio") inicia o loop de eventos e bloqueia, lendo requisições de stdin e escrevendo respostas para stdout.
Este servidor não tem ferramentas ainda, um cliente pode se conectar e negociar, mas não há nada para chamar.

2. Registrando uma Ferramenta

Adicione uma ferramenta chamável usando o decorador @mcp.tool().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("weather-server")
 
@mcp.tool()
def get_weather(city: str) -> str:
    """Retorna um breve resumo do clima para uma cidade."""
    return f"Está ensolarado em {city}."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

O decorador registra get_weather no manifesto de capacidade do servidor, para que ele apareça durante a negociação.
A dica de tipo (city: str) se torna o esquema de entrada da ferramenta, o cliente usa isso para saber quais argumentos enviar.
A docstring se torna a descrição da ferramenta, mostrada ao cliente e ao Claude ao decidir se deve chamá-la.
Sem o decorador, esta seria apenas uma função Python, invisível para qualquer cliente conectado.

3. Registrando um Recurso

Exponha conteúdo somente leitura em uma URI usando @mcp.resource().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("config-server")
 
@mcp.resource("config://settings")
def get_settings() -> str:
    return "theme=dark\ntimezone=UTC"

Recursos são somente leitura, um cliente os busca por URI, eles não recebem argumentos como as ferramentas.
O esquema URI (config://) é arbitrário, escolha um que descreva o que o recurso representa.
Use recursos para dados que um cliente deve ser capaz de ler diretamente, e ferramentas para ações que realizam trabalho ou têm efeitos colaterais.
Um erro comum é expor dados somente leitura como uma ferramenta quando um recurso é o ajuste mais adequado.

4. Registrando um Prompt

Forneça um modelo de prompt reutilizável com @mcp.prompt().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("prompt-server")
 
@mcp.prompt()
def summarize_request(topic: str) -> str:
    return f"Por favor, resuma as últimas atualizações sobre {topic} em três pontos."

Prompts são modelos que o cliente pode buscar e preencher, não dados e não uma ação.
Argumentos para uma função de prompt funcionam da mesma forma que argumentos de ferramenta, eles definem o esquema de entrada do modelo.
Prompts são úteis para padronizar requisições comuns em todos os clientes que se conectam a este servidor.
Um servidor pode misturar ferramentas, recursos e prompts livremente, todos são registrados da mesma forma, com um decorador diferente.

5. Executando o Servidor Localmente

Inicie o servidor como um subprocesso que um cliente pode gerar.

python server.py

Via stdio, o cliente é responsável por iniciar este processo, você raramente o executa isoladamente em uso de produção.
Durante o desenvolvimento local, muitos clientes (como o Claude Desktop) são configurados para iniciar este comando automaticamente quando necessário.
Se o processo sair imediatamente, verifique se há uma exceção no momento da importação. Erros durante a inicialização muitas vezes se parecem com um "servidor não respondendo" do lado do cliente, em vez de um traceback claro do Python.
stdio é o transporte correto para desenvolvimento local, em uma única máquina. Múltiplos clientes remotos exigem HTTP/SSE em vez disso.

Relacionado: Comparação de Implantação de Servidores MCP stdio vs HTTP/SSE - quando ir além do stdio

Exemplos Intermediários

6. Um Servidor com Ferramenta, Recurso e Prompt Juntos

Combine todos os três tipos de capacidade em um servidor, espelhando uma pequena implantação real.

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
TICKETS = {"T-1": "Aberto: impressora offline", "T-2": "Fechado: problema de VPN"}
 
@mcp.tool()
def get_ticket(ticket_id: str) -> str:
    """Busca um ticket de suporte por ID."""
    return TICKETS.get(ticket_id, "Ticket não encontrado.")
 
@mcp.resource("tickets://open")
def list_open_tickets() -> str:
    return "\n".join(k for k, v in TICKETS.items() if v.startswith("Open"))
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    return f"Revise o ticket {ticket_id} e sugira uma próxima ação."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

get_ticket realiza uma busca, então é uma ferramenta. list_open_tickets são dados somente leitura, então é um recurso.
Todas as três capacidades são registradas independentemente e aparecem juntas no manifesto que um cliente vê durante a negociação.
Servidores reais raramente expõem apenas um tipo de capacidade, a maioria das integrações úteis mistura ações e estado legível.
Este dicionário TICKETS em memória é bom para uma demonstração, um servidor de produção o apoiaria com um banco de dados real.

7. Equivalente Mínimo em TypeScript

O mesmo padrão de registro de ferramenta usando o SDK oficial de TypeScript.

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: "weather-server", version: "1.0.0" });
 
server.tool(
  "get_weather",
  { city: z.string() },
  async ({ city }) => ({
    content: [{ type: "text", text: `It is sunny in ${city}.` }],
  })
);
 
await server.connect(new StdioServerTransport());

McpServer desempenha o mesmo papel que FastMCP, ele gerencia a conexão e a negociação para você.
Esquemas zod definem a forma de entrada da ferramenta, o equivalente em TypeScript das dicas de tipo do Python.
server.connect(new StdioServerTransport()) é a versão do SDK TypeScript de mcp.run(transport="stdio").
Ambos os SDKs implementam o mesmo protocolo, então um cliente não pode dizer se um servidor foi escrito em Python ou TypeScript.

Relacionado: Construindo um Servidor MCP com o SDK TypeScript - um guia completo do SDK TypeScript

8. Verificando o Ciclo de Vida Localmente

Uma verificação manual rápida para garantir que seu servidor negocia corretamente antes de conectá-lo a um cliente real.

npx @modelcontextprotocol/inspector python server.py

O Inspetor MCP é uma ferramenta de propósito geral para se conectar a qualquer servidor local e exercitar manualmente suas ferramentas, recursos e prompts.
Ele executa os mesmos passos de conexão e negociação que um cliente real faria, e então permite que você chame ferramentas interativamente.
Executar isso antes de apontar um cliente real para seu servidor pega erros de registro cedo, uma ferramenta faltando no manifesto é óbvia aqui.
Isso é apenas um auxílio de desenvolvimento, não faz parte do ciclo de vida da requisição em si, apenas uma forma de observá-lo.

Relacionado: Como Servidores MCP Lidam com Requisições - o ciclo de vida que esta inspeção está verificando | Testando Servidores MCP Antes da Implantação - testes automatizados para os mesmos manipuladores

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e os SDKs atuais do Model Context Protocol Python/TypeScript. Nomes de modelos, versões de SDK e a especificação MCP mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs e modelcontextprotocol.io antes de confiar neles.

Noções Básicas de Servidores MCP

8 exemplos para você começar a construir servidores MCP - 5 básicos e 3 intermediários.

Pré-requisitos

Python 3.10+ e o SDK Python oficial do MCP: pip install mcp.
Ou Node.js 18+ e o SDK TypeScript oficial do MCP: npm install @modelcontextprotocol/sdk.
Um cliente para se comunicar com seu servidor. Claude Desktop, Claude Code ou um cliente personalizado construído no SDK do Agente funcionam para testes locais via stdio.
Nenhuma configuração de rede é necessária para os exemplos abaixo. Todos eles rodam via stdio, o transporte local padrão para desenvolvimento.

Exemplos Básicos

1. Esqueleto Mínimo de Servidor

O menor servidor MCP possível: crie uma instância e execute-a via stdio.

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("demo-server")
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

FastMCP é a classe de servidor de alto nível no SDK Python; ela cuida das fases de conexão e negociação de capacidade para você.
A string "demo-server" é o nome do servidor, que um cliente pode exibir ao listar servidores conectados.
mcp.run(transport="stdio") inicia o loop de eventos e bloqueia, lendo requisições de stdin e escrevendo respostas para stdout.
Este servidor não tem ferramentas ainda, um cliente pode se conectar e negociar, mas não há nada para chamar.

2. Registrando uma Ferramenta

Adicione uma ferramenta chamável usando o decorador @mcp.tool().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("weather-server")
 
@mcp.tool()
def get_weather(city: str) -> str:
    """Retorna um breve resumo do clima para uma cidade."""
    return f"Está ensolarado em {city}."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

O decorador registra get_weather no manifesto de capacidade do servidor, para que ele apareça durante a negociação.
A dica de tipo (city: str) se torna o esquema de entrada da ferramenta, o cliente usa isso para saber quais argumentos enviar.
A docstring se torna a descrição da ferramenta, mostrada ao cliente e ao Claude ao decidir se deve chamá-la.
Sem o decorador, esta seria apenas uma função Python, invisível para qualquer cliente conectado.

3. Registrando um Recurso

Exponha conteúdo somente leitura em uma URI usando @mcp.resource().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("config-server")
 
@mcp.resource("config://settings")
def get_settings() -> str:
    return "theme=dark\ntimezone=UTC"

Recursos são somente leitura, um cliente os busca por URI, eles não recebem argumentos como as ferramentas.
O esquema URI (config://) é arbitrário, escolha um que descreva o que o recurso representa.
Use recursos para dados que um cliente deve ser capaz de ler diretamente, e ferramentas para ações que realizam trabalho ou têm efeitos colaterais.
Um erro comum é expor dados somente leitura como uma ferramenta quando um recurso é o ajuste mais adequado.

4. Registrando um Prompt

Forneça um modelo de prompt reutilizável com @mcp.prompt().

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("prompt-server")
 
@mcp.prompt()
def summarize_request(topic: str) -> str:
    return f"Por favor, resuma as últimas atualizações sobre {topic} em três pontos."

Prompts são modelos que o cliente pode buscar e preencher, não dados e não uma ação.
Argumentos para uma função de prompt funcionam da mesma forma que argumentos de ferramenta, eles definem o esquema de entrada do modelo.
Prompts são úteis para padronizar requisições comuns em todos os clientes que se conectam a este servidor.
Um servidor pode misturar ferramentas, recursos e prompts livremente, todos são registrados da mesma forma, com um decorador diferente.

5. Executando o Servidor Localmente

Inicie o servidor como um subprocesso que um cliente pode gerar.

python server.py

Via stdio, o cliente é responsável por iniciar este processo, você raramente o executa isoladamente em uso de produção.
Durante o desenvolvimento local, muitos clientes (como o Claude Desktop) são configurados para iniciar este comando automaticamente quando necessário.
Se o processo sair imediatamente, verifique se há uma exceção no momento da importação. Erros durante a inicialização muitas vezes se parecem com um "servidor não respondendo" do lado do cliente, em vez de um traceback claro do Python.
stdio é o transporte correto para desenvolvimento local, em uma única máquina. Múltiplos clientes remotos exigem HTTP/SSE em vez disso.

Relacionado: Comparação de Implantação de Servidores MCP stdio vs HTTP/SSE - quando ir além do stdio

Exemplos Intermediários

6. Um Servidor com Ferramenta, Recurso e Prompt Juntos

Combine todos os três tipos de capacidade em um servidor, espelhando uma pequena implantação real.

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
TICKETS = {"T-1": "Aberto: impressora offline", "T-2": "Fechado: problema de VPN"}
 
@mcp.tool()
def get_ticket(ticket_id: str) -> str:
    """Busca um ticket de suporte por ID."""
    return TICKETS.get(ticket_id, "Ticket não encontrado.")
 
@mcp.resource("tickets://open")
def list_open_tickets() -> str:
    return "\n".join(k for k, v in TICKETS.items() if v.startswith("Open"))
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    return f"Revise o ticket {ticket_id} e sugira uma próxima ação."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

get_ticket realiza uma busca, então é uma ferramenta. list_open_tickets são dados somente leitura, então é um recurso.
Todas as três capacidades são registradas independentemente e aparecem juntas no manifesto que um cliente vê durante a negociação.
Servidores reais raramente expõem apenas um tipo de capacidade, a maioria das integrações úteis mistura ações e estado legível.
Este dicionário TICKETS em memória é bom para uma demonstração, um servidor de produção o apoiaria com um banco de dados real.

7. Equivalente Mínimo em TypeScript

O mesmo padrão de registro de ferramenta usando o SDK oficial de TypeScript.

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: "weather-server", version: "1.0.0" });
 
server.tool(
  "get_weather",
  { city: z.string() },
  async ({ city }) => ({
    content: [{ type: "text", text: `It is sunny in ${city}.` }],
  })
);
 
await server.connect(new StdioServerTransport());

McpServer desempenha o mesmo papel que FastMCP, ele gerencia a conexão e a negociação para você.
Esquemas zod definem a forma de entrada da ferramenta, o equivalente em TypeScript das dicas de tipo do Python.
server.connect(new StdioServerTransport()) é a versão do SDK TypeScript de mcp.run(transport="stdio").
Ambos os SDKs implementam o mesmo protocolo, então um cliente não pode dizer se um servidor foi escrito em Python ou TypeScript.

Relacionado: Construindo um Servidor MCP com o SDK TypeScript - um guia completo do SDK TypeScript

8. Verificando o Ciclo de Vida Localmente

Uma verificação manual rápida para garantir que seu servidor negocia corretamente antes de conectá-lo a um cliente real.

npx @modelcontextprotocol/inspector python server.py

O Inspetor MCP é uma ferramenta de propósito geral para se conectar a qualquer servidor local e exercitar manualmente suas ferramentas, recursos e prompts.
Ele executa os mesmos passos de conexão e negociação que um cliente real faria, e então permite que você chame ferramentas interativamente.
Executar isso antes de apontar um cliente real para seu servidor pega erros de registro cedo, uma ferramenta faltando no manifesto é óbvia aqui.
Isso é apenas um auxílio de desenvolvimento, não faz parte do ciclo de vida da requisição em si, apenas uma forma de observá-lo.

Relacionado: Como Servidores MCP Lidam com Requisições - o ciclo de vida que esta inspeção está verificando | Testando Servidores MCP Antes da Implantação - testes automatizados para os mesmos manipuladores

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e os SDKs atuais do Model Context Protocol Python/TypeScript. Nomes de modelos, versões de SDK e a especificação MCP mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs e modelcontextprotocol.io antes de confiar neles.

Noções Básicas de Servidores MCP

Buscar na documentação

Noções Básicas de Servidores MCP