Para os desenvolvedores de clientes

Comece a construir seu próprio cliente que pode se integrar a todos os servidores MCP.

Neste tutorial, você aprenderá como construir um cliente de chatbot alimentado por LLM que se conecta a servidores MCP. É útil ter passado pelo Início Rápido do Servidor que o guia pelos conceitos básicos de construção do seu primeiro servidor.

Python

Você pode encontrar o código completo para este tutorial aqui.

Requisitos do Sistema

Antes de começar, certifique-se de que seu sistema atenda a estes requisitos:

Computador Mac ou Windows

Última versão do Python instalada

Última versão do uv instalada

Configurando seu Ambiente

Primeiro, crie um novo projeto Python com uv:

Configurando sua Chave de API

Você precisará de uma chave de API Anthropic do Console Anthropic.

Crie um arquivo .env para armazená-la:

Adicione sua chave ao arquivo .env:

Adicione .env ao seu .gitignore:

Certifique-se de manter sua ANTHROPIC_API_KEY segura!

Criando o Cliente

Estrutura Básica do Cliente

Primeiro, vamos configurar nossas importações e criar a classe básica do cliente:

Gerenciamento de Conexão com o Servidor

Em seguida, implementaremos o método para conectar a um servidor MCP:

Lógica de Processamento de Consultas

Agora, vamos adicionar a funcionalidade principal para processar consultas e lidar com chamadas de ferramentas:

Interface de Chat Interativa

Agora, vamos adicionar o loop de chat e a funcionalidade de limpeza:

Ponto de Entrada Principal

Finalmente, vamos adicionar a lógica de execução principal:

Você pode encontrar o arquivo client.py completo aqui.

Componentes Chave Explicados

1. Inicialização do Cliente

A classe MCPClient inicializa com gerenciamento de sessão e clientes de API

Usa AsyncExitStack para gerenciamento adequado de recursos

Configura o cliente Anthropic para interações com Claude

2. Conexão com o Servidor

Suporta servidores Python e Node.js

Valida o tipo de script do servidor

Configura canais de comunicação adequados

Inicializa a sessão e lista as ferramentas disponíveis

3. Processamento de Consultas

Mantém o contexto da conversa

Lida com as respostas de Claude e chamadas de ferramentas

Gerencia o fluxo de mensagens entre Claude e as ferramentas

Combina resultados em uma resposta coerente

4. Interface Interativa

Fornece uma interface de linha de comando simples

Lida com a entrada do usuário e exibe as respostas

Inclui tratamento básico de erros

Permite saída graciosa

5. Gerenciamento de Recursos

Limpeza adequada de recursos

Tratamento de erros para problemas de conexão

Procedimentos de desligamento graciosos

Pontos Comuns de Personalização

Manipulação de Ferramentas

Modifique process_query() para lidar com tipos de ferramentas específicos

Adicione tratamento de erros personalizado para chamadas de ferramentas

Implemente formatação de resposta específica da ferramenta

Processamento de Respostas

Personalize como os resultados das ferramentas são formatados

Adicione filtragem ou transformação de resposta

Implemente registro personalizado

Interface do Usuário

Adicione uma GUI ou interface web

Implemente saída de console rica

Adicione histórico de comandos ou preenchimento automático

Executando o Cliente

Para executar seu cliente com qualquer servidor MCP:

Se você estiver continuando o tutorial do clima do início rápido do servidor, seu comando pode ser algo como: python client.py .../weather/src/weather/server.py

O cliente irá:

Conectar-se ao servidor especificado

Listar as ferramentas disponíveis

Iniciar uma sessão de chat interativa onde você pode:

Inserir consultas

Ver execuções de ferramentas

Obter respostas de Claude

Aqui está um exemplo de como deve ser se conectado ao servidor do clima do início rápido do servidor:

Como Funciona

Quando você envia uma consulta:

O cliente obtém a lista de ferramentas disponíveis do servidor

Sua consulta é enviada para Claude junto com as descrições das ferramentas

Claude decide quais ferramentas (se houver) usar

O cliente executa quaisquer chamadas de ferramentas solicitadas através do servidor

Os resultados são enviados de volta para Claude

Claude fornece uma resposta em linguagem natural

A resposta é exibida para você

Melhores práticas

Tratamento de Erros

Sempre envolva as chamadas de ferramentas em blocos try-catch

Forneça mensagens de erro significativas

Lide graciosamente com problemas de conexão

Gerenciamento de Recursos

Use AsyncExitStack para limpeza adequada

Feche as conexões quando terminar

Lide com desconexões do servidor

Segurança

Armazene as chaves de API com segurança em .env

Valide as respostas do servidor

Seja cauteloso com as permissões das ferramentas

Solução de Problemas

Problemas de Caminho do Servidor

Verifique se o caminho para o script do servidor está correto

Use o caminho absoluto se o caminho relativo não estiver funcionando

Para usuários do Windows, certifique-se de usar barras (/) ou barras invertidas escapadas (\) no caminho

Verifique se o arquivo do servidor tem a extensão correta (.py para Python ou .js para Node.js)

Exemplo de uso correto do caminho:

Tempo de Resposta

A primeira resposta pode levar até 30 segundos para retornar

Isso é normal e acontece enquanto:

O servidor inicializa

Claude processa a consulta

As ferramentas estão sendo executadas

As respostas subsequentes são normalmente mais rápidas

Não interrompa o processo durante este período de espera inicial

Mensagens de Erro Comuns

Se você vir:

FileNotFoundError: Verifique o caminho do seu servidor

Connection refused: Certifique-se de que o servidor está em execução e o caminho está correto

Tool execution failed: Verifique se as variáveis de ambiente necessárias da ferramenta estão definidas

Timeout error: Considere aumentar o tempo limite na configuração do seu cliente

Python#

Requisitos do Sistema#

Configurando seu Ambiente#

Configurando sua Chave de API#

Criando o Cliente#

Estrutura Básica do Cliente#

Gerenciamento de Conexão com o Servidor#

Lógica de Processamento de Consultas#

Interface de Chat Interativa#

Ponto de Entrada Principal#

Componentes Chave Explicados#

1. Inicialização do Cliente#

2. Conexão com o Servidor#

3. Processamento de Consultas#

4. Interface Interativa#

5. Gerenciamento de Recursos#

Pontos Comuns de Personalização#

Executando o Cliente#

Como Funciona#

Melhores práticas#

Solução de Problemas#

Problemas de Caminho do Servidor#

Tempo de Resposta#

Mensagens de Erro Comuns#