Aprenda a usar o IBM Bob para criar um servidor Model Context Protocol (MCP) personalizado que conecta modelos de IA a ferramentas e fontes de dados externas. Abrange modo avançado, fluxo de aprovação e configuração MCP neste tutorial prático.

Neste tutorial, você usa o IBM Bob para criar um servidor MCP personalizado que fornece acesso somente leitura ao arXiv, um repositório de conteúdo de acesso aberto para artigos científicos. Opcionalmente, você pode estender o servidor para integrar com um agente de IA do watsonx Orchestrate.

O Model Context Protocol (MCP) é um padrão aberto que permite que grandes modelos de linguagem (LLMs) se comuniquem com ferramentas externas, fontes de dados e repositórios de conteúdo por meio de uma arquitetura cliente-servidor unificada. Antes do MCP, cada assistente de IA precisava de sua própria integração específica para cada ferramenta externa, usando function calling sem interoperabilidade. Em vez disso, o MCP define um único protocolo JSON-RPC 2.0 que qualquer host MCP pode usar para se conectar a qualquer servidor MCP.

Pré-requisitos

Este tutorial cria um servidor MCP em TypeScript que consulta a API do arXiv. Não requer experiência prévia com TypeScript ou integração MCP.

Para concluir este tutorial, você precisa do seguinte:

IBM Bob IDE

Baixe e instale o aplicativo IBM Bob no seu computador. O Bob é um aplicativo IDE independente, não uma extensão.

Node.js

Instale o Node.js 22 ou posterior para criar e executar o servidor MCP TypeScript localmente.

Configurar seu workspace

Inicie o IBM Bob, abra o painel de configurações MCP e prepare um diretório de trabalho para o projeto do servidor.

Iniciar o IBM Bob

Inicie o aplicativo IBM Bob no seu computador.

Abrir o painel de chat do Bob

Se o painel de chat ainda não estiver aberto, clique no ícone do Bob ao lado da barra de navegação ou use o atalho Option + Command + B (Mac) ou Ctrl + Alt + B (Windows).

Abrir o painel de configurações MCP

Clique no ícone de engrenagem no canto superior direito da janela de chat e selecione MCP na barra lateral esquerda.

O painel de configurações MCP permite gerenciar o controle de acesso habilitando ou desabilitando servidores, aprovando automaticamente ferramentas específicas, e criando integrações personalizadas com o SDK MCP.

Global: Armazenado em mcp_settings.json, aplicado em todos os workspaces.
Projeto: Armazenado em .bob/mcp.json na raiz do projeto, compartilhável com sua equipe via controle de versão. As configurações no nível do projeto substituem as globais.

Configurar aprovação automática

No chat do Bob, certifique-se de que as permissões de aprovação automática logo abaixo do campo de entrada do chat estejam definidas como somente "Read". Essa configuração permite que o Bob visualize seus arquivos e o conteúdo do diretório, enquanto solicita sua revisão e aprovação antes de executar cada comando.

Abrir o diretório do projeto

Se você tiver um diretório preferido para o projeto, abra-o na IDE. Você também pode pedir ao Bob para fazer isso na janela de chat.

Configurar um ambiente virtual Python

É uma prática comum criar ambientes virtuais Python para isolar as dependências de um projeto, de modo que projetos diferentes não entrem em conflito entre si. Mude o Bob para o modo Agent — o modo que pode ler, escrever e executar comandos no terminal — e crie o ambiente.

Criar e ativar o ambiente virtual

No painel de chat do Bob, insira o seguinte prompt:

In this directory, activate a Python virtual environment.

O Bob executa uma série de comandos no terminal. Aprove cada um quando solicitado. Os comandos criam um novo ambiente virtual no diretório venv/ e o ativam.

Gerar o plano de construção do servidor MCP

Mudar para o modo Plan

Clique no botão logo abaixo do campo de entrada do chat para alterar o modo de interação para Plan. Esse modo permite que o Bob gere um plano estruturado para o servidor MCP antes de escrever qualquer código.

Enviar os requisitos do servidor

Com o ambiente virtual ativo, envie o seguinte prompt ao Bob. Fornecer requisitos específicos antecipadamente dá ao Bob contexto suficiente para formular um plano completo antes de escrever qualquer código:

Create an MCP server named arxiv-server that provides read-only access to arXiv. The server should:
- Expose one tool, search_papers, for querying arXiv papers by keyword
- Accept a query string and an optional max_results parameter (default 5, max 20)
- Limit results to paper metadata and abstracts (no PDFs)
- Return title, authors, publication date, abstract, and arXiv URL for each result
- Normalize responses into a clean, structured JSON schema
- Handle API errors and empty results gracefully, returning a clear message instead of failing
- Use TypeScript/Node.js with the stdio transport
- Use the arXiv API v2, which requires no authentication

O Bob produz uma lista de tarefas estruturada que cobre o scaffolding do projeto, implementação do servidor MCP, instalação de dependências, configuração do servidor e testes. Observe que o Bob planeja o tratamento de erros e as considerações de autenticação automaticamente. Mesmo quando a API de destino (arXiv) não requer uma chave, o Bob indica onde as credenciais seriam injetadas para servidores que necessitam.

Se o Bob fizer perguntas de esclarecimento, responda-as da melhor forma possível ou diga ao Bob para fazer suposições razoáveis.

Criar e revisar o servidor MCP

Depois de revisar e aprovar o plano, mude para o modo Agent para executar cada etapa. Seu resultado e ordem podem variar ligeiramente do exemplo a seguir, pois o Bob gera respostas em tempo real.

Diga ao Bob para começar a criar o servidor com o seguinte prompt:

Implement the plan.

Primeiro, o Bob cria o scaffolding da estrutura do projeto e executa mkdir -p arxiv-server/src para criar o diretório do projeto.

Em seguida, o Bob gera arxiv-server/package.json, o hub de configuração do Node.js que declara os metadados, scripts e dependências do projeto:

{
  "name": "arxiv-server",
  "version": "0.1.0",
  "description": "MCP server for read-only access to arXiv papers",
  "type": "module",
  "bin": {
    "arxiv-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
    "prepare": "npm run build",
    "watch": "tsc --watch"
  },
  "keywords": ["mcp", "arxiv", "research", "papers"],
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4",
    "axios": "^1.7.9",
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "@types/node": "^22.10.5",
    "typescript": "^5.7.3"
  }
}

O Bob também cria arxiv-server/tsconfig.json para configurar o compilador TypeScript:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

Em seguida, o Bob cria o arquivo principal do servidor em arxiv-server/src/index.ts. Esse arquivo registra a ferramenta search_arxiv no SDK MCP, implementa a análise XML-para-JSON para as respostas da API do arXiv, impõe limites de resultados e inicia o servidor no transporte STDIO — o tipo de transporte local e de baixa latência adequado para servidores em execução na mesma máquina que o host MCP.

A chamada server.tool() do SDK MCP é o principal ponto de integração. Ela expõe a ferramenta para qualquer cliente MCP.

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios from 'axios';

interface ArxivEntry {
  id: string;
  title: string;
  summary: string;
  authors: Array<{ name: string }>;
  published: string;
  updated: string;
  categories: string[];
  primary_category: string;
  links: Array<{ href: string; rel: string; type?: string }>;
}

interface ArxivSearchResult {
  entries: ArxivEntry[];
  totalResults: number;
  startIndex: number;
  itemsPerPage: number;
}

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

const arxivApi = axios.create({
  baseURL: 'http://export.arxiv.org/api',
  timeout: 30000,
});

server.tool(
  "search_arxiv",
  {
    query: z.string().describe("Search query (supports arXiv query syntax)"),
    max_results: z.number().min(1).max(50).optional()
      .describe("Maximum results to return (1–50, default: 10)"),
    start: z.number().min(0).optional()
      .describe("Starting index for pagination (default: 0)"),
    sort_by: z.enum(["relevance", "lastUpdatedDate", "submittedDate"]).optional(),
    sort_order: z.enum(["ascending", "descending"]).optional()
  },
  async ({ query, max_results = 10, start = 0, sort_by = "relevance", sort_order = "descending" }) => {
    try {
      const params: Record<string, string | number> = {
        search_query: query,
        start: Math.max(start, 0),
        max_results: Math.min(max_results, 50),
        ...(sort_by && { sortBy: sort_by }),
        ...(sort_order && { sortOrder: sort_order }),
      };
      const response = await arxivApi.get('/query', { params });
      return {
        content: [{ type: "text", text: formatSearchResults(parseArxivXML(response.data)) }],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [{ type: "text", text: `arXiv API error: ${error.response?.data?.message ?? error.message}` }],
          isError: true,
        };
      }
      throw error;
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error('arXiv MCP server running on stdio');

O sinalizador isError: true no bloco catch é o padrão de tratamento de erros padrão do MCP. Ele sinaliza ao cliente MCP que a chamada de ferramenta falhou sem encerrar o processo do servidor.

Como próximo passo, o Bob instala as dependências no diretório arxiv-server executando cd arxiv-server && npm install.

Registrar o servidor no escopo do projeto

O Bob não registra um novo servidor automaticamente. Diga ao Bob para adicioná-lo explicitamente e especifique o escopo do projeto para que a configuração fique em .bob/mcp.json e possa ser compartilhada com sua equipe via controle de versão.

Dizer ao Bob para registrar o servidor

No painel de chat do Bob, insira o seguinte prompt:

Register the arxiv-server as an MCP server at project scope. Build it first if needed, then add it to .bob/mcp.json.

Revisar a configuração gerada

O Bob escreve o seguinte em .bob/mcp.json na raiz do seu projeto. Os campos command e args informam ao cliente MCP como iniciar o processo do servidor usando o transporte STDIO.

{
  "mcpServers": {
    "arxiv-server": {
      "command": "node",
      "args": ["${workspaceFolder}/arxiv-server/build/index.js"]
    }
  }
}

Confirmar que o servidor está carregado

O Bob recarrega a configuração MCP automaticamente após escrever este arquivo. Abra o painel de configurações MCP (ícone de engrenagem > MCP) para confirmar que o servidor arxiv-server está listado e habilitado antes de continuar. Se não aparecer, clique no ícone de recarregar ao lado da lista de servidores.

Reiniciar o Bob

Reinicie o Bob para garantir que o servidor esteja em execução e pronto para aceitar consultas.

Testar o servidor MCP

Com o servidor registrado, o Bob executa automaticamente duas consultas de validação na ferramenta search_arxiv.

A primeira consulta busca três artigos de computação quântica classificados por relevância. A segunda busca dois artigos de aprendizado de máquina classificados por data de envio decrescente. Ambas são executadas com sucesso, confirmando que a ferramenta está acessível e que o tratamento de erros do servidor gerencia corretamente diferentes combinações de parâmetros.

Agora execute suas próprias consultas para verificar se o Bob extrai os parâmetros corretos da linguagem natural. Um exemplo de prompt para colar no painel de chat do Bob:

What are the latest papers on LLM agent tracing?

Documentar o servidor

Implementações de servidor MCP open source geralmente incluem documentação para que outros possam começar rapidamente. Peça ao Bob para gerá-la:

In this directory, create a README.md file to document this MCP server.
Include setup and usage instructions.

O Bob produz um README.md abrangente cobrindo instalação, configuração para múltiplos hosts MCP (IBM Bob, Claude Desktop, Cursor, Claude Code), orientações de autenticação para servidores que requerem chaves de API, padrões de acesso a arquivos locais e dicas de solução de problemas.

Limpar recursos

Este tutorial cria arquivos locais e um registro de servidor. Remova-os se não planeja continuar usando o servidor MCP do arXiv.

Abra o painel de configurações MCP no Bob (ícone de engrenagem > MCP) e desabilite ou exclua a entrada arxiv-server. Alternativamente, remova o bloco arxiv-server de mcp_settings.json (escopo global) ou .bob/mcp.json (escopo do projeto) diretamente.

Próximos passos

Neste tutorial, você usou o IBM Bob para criar um servidor MCP em TypeScript, configurá-lo com o transporte STDIO e testá-lo com consultas ao vivo no arXiv — tudo por meio de prompts em linguagem natural.

O mesmo fluxo de trabalho se aplica a implementações de servidores MCP mais complexas: servidores que se conectam a bancos de dados, arquivos locais ou qualquer outra fonte de dados externa. Servidores que requerem autenticação precisam de credenciais injetadas como variáveis de ambiente no JSON de configuração MCP. Para implantações remotas, substitua o transporte STDIO pelo SSE.

Conheça a função Code review do Bob para detectar problemas antes de fazer commit do código do servidor.

Conheça os modos para entender quando usar os modos Advanced, Code, Ask e outros personas do Bob.

Explore a configuração MCP para detalhes sobre escopo global vs. de projeto, ferramentas aprovadas automaticamente e configuração de transporte SSE.

Siga a série de tutoriais Get started with IBM Bob para continuar aprendendo.

Criando servidores MCP com IBM Bob