Conceitos Básicos do MCP Core

9 exemplos para você começar com os Conceitos Básicos do MCP - 6 básicos e 3 intermediários.

Pré-requisitos

• Python 3.10 ou posterior.
• Instale o SDK oficial do Python MCP: pip install mcp.
• Um terminal para executar o servidor como um processo local; nenhuma configuração de rede é necessária para stdio.

Exemplos Básicos

1. Instale e Importe o SDK

Confirme se o SDK está instalado e importe as partes necessárias para um servidor mínimo.

# server.py
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("basics-demo")

• FastMCP é a classe de servidor de alto nível no SDK oficial do Python, construída para definições rápidas de ferramentas/recursos/prompts.
• A string passada para FastMCP nomeia o servidor; os clientes exibem esse nome ao listar conexões.
• Este objeto é o único ponto de entrada ao qual você anexa ferramentas, recursos e prompts.

2. Defina uma Única Ferramenta

Registre uma única ferramenta chamável usando um decorador, a maneira mais simples de expor uma função a um cliente.

@mcp.tool()
def add(a: int, b: int) -> int:
    """Soma dois números."""
    return a + b

• O decorador @mcp.tool() transforma uma função Python comum em uma ferramenta MCP detectável.
• Dicas de tipo (a: int, b: int) se tornam automaticamente o esquema de entrada da ferramenta.
• A docstring se torna a descrição da ferramenta, que o modelo lê para decidir quando chamá-la.

Relacionado: Definindo Ferramentas Chamáveis em um Servidor MCP - esquema completo de ferramentas e padrões de manipuladores

3. Execute o Servidor Via stdio

Inicie o servidor para que um cliente local possa criá-lo como um subprocesso e se comunicar com ele via entrada e saída padrão.

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

• transport="stdio" é o transporte mais simples: o servidor lê requisições do stdin e escreve respostas no stdout.
• stdio é o padrão correto para ferramentas locais que rodam ao lado do cliente na mesma máquina.
• Nenhuma configuração de porta, TLS ou autenticação é necessária para um servidor stdio.

Relacionado: Escolhendo Entre os Transportes stdio e HTTP/SSE para MCP - quando usar um transporte remoto em vez disso

4. Conecte um Cliente ao Servidor

Use os auxiliares de cliente do SDK Python para iniciar o processo do servidor e abrir uma sessão.

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
 
params = StdioServerParameters(command="python", args=["server.py"])
 
async def main():
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print("Conectado a:", session)
 
asyncio.run(main())

• StdioServerParameters informa ao cliente como iniciar o processo do servidor (comando mais argumentos).
• stdio_client abre o subprocesso e produz fluxos de leitura/escrita para o protocolo.
• session.initialize() executa o handshake do MCP antes que quaisquer chamadas de ferramenta, recurso ou prompt sejam feitas.

5. Liste as Ferramentas do Servidor

Pergunte ao servidor conectado quais ferramentas ele expõe antes de chamar qualquer uma delas.

async with ClientSession(read, write) as session:
    await session.initialize()
    tools = await session.list_tools()
    for tool in tools.tools:
        print(tool.name, "-", tool.description)

• list_tools() realiza a descoberta: o cliente aprende o que está disponível sem codificar nomes de ferramentas.
• Cada ferramenta retornada carrega seu nome, descrição e esquema de entrada.
• Esta é a mesma etapa de descoberta que um cliente real como o Claude Code realiza ao se conectar ao seu servidor.

6. Chame a Ferramenta

Invoque a ferramenta add pelo nome com argumentos correspondentes e leia o resultado.

result = await session.call_tool("add", arguments={"a": 2, "b": 3})
print(result.content)

• call_tool envia o nome da ferramenta e um dicionário de argumentos que correspondem ao esquema da ferramenta.
• O content da resposta contém o valor de retorno da ferramenta, encapsulado no formato de conteúdo do MCP.
• Se os argumentos não corresponderem ao esquema, o servidor retornará um erro em vez de um resultado.

Exemplos Intermediários

7. Adicione uma Segunda Ferramenta e Reconecte

Estenda o mesmo servidor com uma segunda ferramenta para ver como várias ferramentas coexistem em uma única sessão.

@mcp.tool()
def greet(name: str) -> str:
    """Retorna uma saudação amigável para o nome fornecido."""
    return f"Olá, {name}!"
 
# o servidor agora expõe add() e greet()

• Múltiplas funções @mcp.tool() podem existir na mesma instância FastMCP; cada uma se torna sua própria entrada detectável.
• Um cliente que se reconecta (ou chama list_tools() novamente) vê ambas as ferramentas sem nenhum código de registro no lado do servidor.
• Manter cada ferramenta focada em uma única tarefa torna as decisões de seleção de ferramentas do modelo mais fáceis e confiáveis.

8. Manipule um Erro de Ferramenta Gracefully

Levante um erro claro de dentro de um manipulador de ferramenta para que o cliente e o modelo recebam feedback útil em vez de uma falha.

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a por b."""
    if b == 0:
        raise ValueError("b não pode ser zero")
    return a / b

• Levantar uma exceção Python padrão dentro de um manipulador de ferramenta é capturado pelo SDK e retornado ao cliente como um erro de ferramenta.
• Uma mensagem específica e descritiva ajuda o modelo a decidir se deve tentar novamente com argumentos diferentes ou desistir.
• Permitir que as exceções se propaguem sem serem capturadas (em vez de travar o processo) mantém o servidor disponível para a próxima chamada.

9. Integre o Servidor ao Claude Desktop

Aponte um cliente MCP real para o seu servidor stdio usando seu arquivo de configuração, em vez do cliente feito manualmente do exemplo 4.

{
  "mcpServers": {
    "basics-demo": {
      "command": "python",
      "args": ["/caminho/absoluto/para/server.py"]
    }
  }
}

• O Claude Desktop (e clientes semelhantes) iniciam servidores stdio lendo uma lista de comandos e argumentos de um arquivo de configuração, exatamente como StdioServerParameters.
• Usar um caminho absoluto para server.py evita problemas de diretório de trabalho quando o cliente inicia o processo.
• Uma vez configurado, o mesmo código de servidor que você testou com um cliente feito manualmente agora pode ser chamado a partir da interface de conversação do Claude.

Relacionado: Ferramentas MCP vs. Recursos vs. Prompts Comparação - decida o que expor a seguir à medida que seu servidor cresce

Relacionados

• Entendendo MCP: Ferramentas, Recursos e Prompts - a base conceitual por trás do que você acabou de construir.
• Definindo Ferramentas Chamáveis em um Servidor MCP - esquemas e manipuladores em profundidade, além de uma única ferramenta de demonstração.
• Expondo Dados Legíveis como Recursos MCP - o próximo primitivo a ser adicionado a este servidor.
• Boas Práticas do MCP Core Concepts - uma lista de verificação depois de passar de um protótipo de ferramenta única.

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 a especificação atual do Model Context Protocol. 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.