Neste tutorial, você criará um Model Context Protocol (MCP) simples, que expõe uma única ferramenta para pesquisar tutoriais da IBM. Ao usar o framework "fastmcp" e a biblioteca de solicitações, o script faz download de um índice JSON de tutoriais de uma URL remota. Em seguida, procura correspondências com a consulta de um usuário e retorna uma lista de resultados formatada de forma organizada. Você também adicionará o tratamento de erros para problemas de rede, JSON ruim e problemas inesperados, tornando a ferramenta robusta e amigável para iniciantes. Por fim, você executará o servidor MCP para que ele possa ser conectado e testado com um cliente como o Cursor.
Desenvolvedores e startups estão desenvolvendo cada vez mais soluções orientadas por [inteligência artificial] generativa (https://www.ibm.com/br-pt/think/topics/artificial-intelligence) (IA). Para tornar suas soluções mais úteis, elas precisam de informações atualizadas e de contexto. [Modelos] de aprendizado de máquina (https://www.ibm.com/br-pt/think/topics/ai-model) precisam interoperar com ferramentas, interfaces de programação de aplicativos(APIs), kits de desenvolvimento de software (SDKs) e sistemas front-end para que isso aconteça.
O MCP padroniza a forma como o contexto é transmitido entre os modelos de IA e sistemas. Simplifica a coordenação em um grande modelo de linguagem (LLM) e fontes e ferramentas de dados externas. Uma analogia comum é pensar no MCP como uma porta USB-C para um LLM. Ele torna um LLM muito mais útil porque o modelo tem acesso a recursos e dados que não faziam parte do treinamento do modelo. Essa capacidade é especialmente útil na criação de agentes de IA.
O MCP foi desenvolvido pela Anthropic e adotado pelos principais provedores de IA, incluindo OpenAI, Google DeepMind e o setor em geral. Ele oferece uma maneira segura e padronizada para os modelos de IA acessarem e usarem dados, recursos (como modelos de prompt) e ferramentas externos.
Além disso, integrated development environments (IDEs), como Cursor e Visual Studio Code, também adotaram o MCP, permitindo que seus assistentes de IA acessem servidores MCP para tornar seu uso mais relevante em contexto e amigável para desenvolvedores. Criadas como um padrão aberto, as organizações usam o MCP para atuar como uma ponte entre o mundo estocástico da IA generativa e o mundo determinístico da maioria dos sistemas empresariais atuais. O MCP fornece ao LLM informações contextuais de forma semelhante a outros padrões de design que começaram a surgir, como retrieval augmented generation (RAG), tool calling e agentes de IA.
Algumas vantagens de usar o MCP em comparação com essas outras soluções são:
- Escala: os servidores MCP podem ser definidos e hospedados uma vez e usados por muitos sistemas de IA. Essa capacidade limita a necessidade de definir o acesso aos mesmos dados de origem, recursos e ferramentas de IA para vários sistemas de IA generativa.
- Recuperação de dados: ao contrário da RAG, onde a recuperação de dados exige pré-processamento e vetorização antes da consulta, o MCP é dinâmico e permite flutuações e atualizações de fontes de informações em tempo real.
- Complexidade: o MCP é bastante simples de configurar e incorporar nas aplicações de IA, como demonstramos aqui. Você pode usar arquivos de configuração facilmente para tornar um servidor MCP portátil em todos os ambientes.
- Independente de plataforma: além do fato de que você pode construir servidores MCP com Python, TypeScript ou outras linguagens, eles também não estão acoplados a uma solução LLM específica.
- Depuração por meio de um modelo cliente/servidor: o cliente MCP envia solicitações ao servidor MCP, que em seguida busca os dados necessários de vários sistemas e fontes externas, sejam APIs, bancos de dados ou arquivos locais. Essa abordagem estruturada garante que o modelo de IA receba contexto consistente e relevante, levando a produções mais precisas e confiáveis. O MCP usa JSON-RPC para codificar mensagens e é compatível com dois mecanismos de transporte, stdio e HTTP transmitível. Em iterações anteriores do protocolo, ele também suportava HTTP com eventos enviados pelo servidor (SSE)
A necessidade de se manter constantemente atualizado com as últimas informações de que sua empresa precisa pode ser assustador. O MCP pode ajudar a criar contexto e incorporar novas informações para contratos à medida que eles são executados, informações legadas que estão sendo digitalizadas, mas não necessariamente digeríveis e muito mais. Essas informações podem ser internas e externas, mas adicionar contexto ignora a necessidade demorada de retreinar um LLM para ser útil.
Há muitos servidores MCP remotos disponíveis, bem como muitas implementações de referência em github.com
Este guia passo a passo pode ser encontrado em nosso repositório do GitHub junto com o script server.py ao qual você fará referência ao criar seu servidor MCP. Neste tutorial, mostraremos como criar um servidor MCP personalizado básico que pode:
Para facilitar este tutorial, criamos um mecanismo pelo qual o servidor que você vai construir pode consumir facilmente nosso conteúdo do tutorial sem a necessidade de autenticação.
- Python 3.11 ou mais recente instalado no seu computador (verifique executando python3 --version em seu terminal).
- O módulo venv integrado está disponível (vem com o Python na maioria dos sistemas; em algumas distribuições do Linux, talvez seja necessário instalá-lo separadamente com sudo apt install python3-venv).
- Um terminal de linha de comando (CLI):
- macOS ou Linux: use seu aplicativo Terminal (esses ambientes são semelhantes ao Unix).
- Windows: use PowerShell ou Prompt de Comando, com pequenas diferenças de sintaxe explicadas na próxima etapa.
- Um editor de texto ou IDE de sua escolha
Crie um novo diretório e cd nele
Certifique-se de que você esteja no diretório
Observação: no Windows, você pode substituir
Depois de criar o ambiente virtual, você precisa ativá-lo usando o seguinte comando
Depois de ativado, seu shell provavelmente mostrará
Agora, você precisa instalar o pacote Python para
Instale o
Após a conclusão dessa etapa, você poderá verificar se o FastMCP está instalado corretamente executando o seguinte comando
Se obter uma saída semelhante à abaixo, você tem o FastMCP instalado em seu ambiente virtual.
FastMCP version: 2.10.1
MCP version: 1.10.1
Python version: 3.11.13
Platform: macOS-15.5-arm64-arm-64bit
FastMCP root path: /opt/homebrew/lib/python3.11/site-packages
Agora você tem o FastMCP instalado; vamos criar nosso servidor MCP.
Crie um novo arquivo no diretório e vamos dar a ele o nome
Quando você tiver esse arquivo, abra-o, copie e cole o seguinte trecho de código nele
Vamos executar o código anterior e explicar o que as partes principais estão fazendo.
O script começa importando o FastMCP, que fornece o framework para a criação de um servidor MCP, e as solicitações usadas para baixar dados por HTTP. Adicionamos uma constante
Em seguida, criamos uma instância de servidor MCP com
O
A pesquisa não diferencia maiúsculas de minúsculas: a consulta é convertida para letras minúsculas, e o título e a URL de cada tutorial também são reduzidos para correspondência. Se um tutorial contiver o termo de pesquisa no título ou na URL, ele será adicionado a uma lista de resultados relevantes.
Se nenhum tutorial corresponder à pesquisa, a função retornará uma mensagem amigável indicando que nada foi encontrado. Se houver correspondências, a função criará uma lista numerada e formatada, mostrando o título, o URL, a data e, se disponível, o autor de cada tutorial. A formatação usa negrito no estilo Markdown nos títulos, para que se destaquem nos clientes que oferecem suporte a ela. O texto formatado final é retornado como uma única string.
A função inclui tratamento de exceções direcionada:
Um manipulador
Cada erro retorna uma mensagem descritiva para o responsável pela chamada, em vez de interromper o programa.
Na parte inferior, o bloco
Agora que você criou seu servidor, é necessário ativá-lo em seu IDE antes de usá-lo. Há muitos clientes que oferecem suporte ao MCP com vários níveis de integração com o protocolo. O site oficial do MCP oferece uma lista completa de exemplos de clientes.
Se você tiver o Cursor instalado, poderá adicionar o servidor MCP dentro do Cursor seguindo estas instruções.
Abra as configurações do Cursor e navegue até Ferramentas e integrações. Selecione Novo servidor MCP e cole no arquivo mcp.json que o Cursor abre em uma nova guia. Certifique-se de substituir <YOUR PATH> pelo diretório em que você está. Você pode executar pwd em seu terminal para obter o caminho completo. Para obter mais informações sobre o Cursor e o MCP, consulte os documentos do Cursor.
{
"mcpServers": {
"tutorials": {
"command": "fastmcp",
"args": ["run <YOUR PATH>/ibmtutorialmcpserver/server.py"],
"env": {
}
}
}
}
Se você for usuário do Microsoft VS Code, poderá adicionar o servidor MCP usando as instruções vinculadas aqui. Certifique-se de que o Copilot esteja configurado no VS Code antes de continuar.
Se você quiser habilitar o servidor MCP usando um arquivo, crie um arquivo .vscode/mcp.json no diretório desse projeto e copie e cole este código no arquivo. Certifique-se de substituir <YOUR PATH> pelo diretório em que você está. Você pode executar pwd em seu terminal para obter o caminho completo.
"servers": {
"IBM Tutorials": {
"type": "stdio",
"command": "fastmcp",
"args": [
"run",
"<YOUR PATH>/ibmtutorialmcpserver/server.py"
]
},
},
Agora que você ativou seu servidor MCP, vamos colocar o servidor em execução para que você possa usar a ferramenta criada em server.py. Se você estiver usando o VS Code, consulte estes documentos.
No bate-papo do IDE, perguntarei "Quais são alguns tutoriais de séries temporais da IBM?" Veja a seguir a saída recebida, mas sua resposta pode variar dependendo do modelo usado e do seu IDE.
Saída:
Here are some IBM time series tutorials:
Time series forecasting with Lag-Llama (zero-shot learning)
Tutorial link
Predict overnight low temperatures using the Lag-Llama model in a zero-shot learning scenario.
Using the watsonx.ai Time Series Forecasting API to predict energy demand
Tutorial link
Predict energy demand with the watsonx.ai Time Series Forecasting API.
Authors: Aleksandra Kłeczek and Meredith Syed
Let me know if you want details or help with a specific tutorial.
Ótimo! O agente pôde usar a ferramenta
Neste tutorial, você aprendeu a construir um servidor MCP para pesquisar em todos os nossos tutoriais usando qualquer cliente MCP de sua preferência. Você criou um servidor MCP com uma única ferramenta de pesquisa que recupera um índice JSON remoto de tutoriais, filtra os resultados com base em um termo de pesquisa e os retorna em um formato legível. Ele usa Fastmcp para registrar e executar a ferramenta, solicitações para buscar os dados e inclui tratamento de erros para rede, análise e problemas inesperados. Quando executado, o servidor pode ser conectado pelos clientes MCP para consulta em tempo real de todos os nossos tutoriais.
Crie, implemente e gerencie assistentes e agentes de IA potentes que automatizam fluxos de trabalho e processos com a IA generativa.
Construa o futuro do seu negócio com soluções de IA em que você pode confiar.
Os serviços de IA da IBM Consulting ajudam a reinventar a forma como as empresas trabalham com IA para gerar transformação.