Impara a usare IBM Bob per creare un server Model Context Protocol (MCP) personalizzato che connette modelli di IA a strumenti esterni e fonti di dati. Copre la modalità avanzata, il flusso di approvazione e la configurazione MCP in questo tutorial pratico.

In questo tutorial, usi IBM Bob per creare un server MCP personalizzato che fornisce accesso in sola lettura ad arXiv, un repository di contenuti ad accesso aperto per articoli scientifici. Facoltativamente, puoi estendere il server per integrarlo con un agente IA watsonx Orchestrate.

Il Model Context Protocol (MCP) è uno standard aperto che consente ai grandi modelli linguistici (LLM) di comunicare con strumenti esterni, fonti di dati e repository di contenuti attraverso un'architettura client-server unificata. Prima di MCP, ogni assistente IA aveva bisogno di una propria integrazione per ogni strumento esterno, usando il function calling senza interoperabilità. MCP definisce invece un unico protocollo JSON-RPC 2.0 che qualsiasi host MCP può usare per connettersi a qualsiasi server MCP.

Prerequisiti

Questo tutorial crea un server MCP in TypeScript che interroga l'API arXiv. Non è richiesta esperienza pregressa in TypeScript o nell'integrazione MCP.

Per completare questo tutorial, hai bisogno di:

IBM Bob IDE

Scarica e installa l'applicazione IBM Bob sul tuo computer. Bob è un'applicazione IDE autonoma e non un'estensione.

Node.js

Installa Node.js 22 o versione successiva per creare ed eseguire il server MCP TypeScript in locale.

Configurare il workspace

Avvia IBM Bob, apri il pannello delle impostazioni MCP e prepara una directory di lavoro per il progetto del server.

Avviare IBM Bob

Avvia l'applicazione IBM Bob sul tuo computer.

Aprire il pannello di chat di Bob

Se il pannello di chat non è già aperto, clicca sull'icona di Bob accanto alla barra di navigazione o usa il tasto di scelta rapida Option + Command + B (Mac) o Ctrl + Alt + B (Windows).

Aprire il pannello delle impostazioni MCP

Clicca sull'icona a ingranaggio nell'angolo in alto a destra della finestra di chat, quindi seleziona MCP dalla barra laterale sinistra.

Il pannello delle impostazioni MCP ti consente di gestire il controllo degli accessi abilitando o disabilitando i server, approvando automaticamente strumenti specifici, e creare integrazioni personalizzate con il MCP SDK.

Globale: Salvato in mcp_settings.json, applicato a tutti i workspace.
Progetto: Salvato in .bob/mcp.json nella radice del progetto, condivisibile con il tuo team tramite il controllo di versione. Le impostazioni a livello di progetto sovrascrivono quelle globali.

Configurare l'approvazione automatica

Nella chat di Bob, assicurati che i permessi di approvazione automatica appena sotto il campo di input della chat siano impostati solo su "Read" (Lettura). Questa configurazione consente a Bob di visualizzare i tuoi file e il contenuto delle directory, richiedendo la tua revisione e approvazione prima di eseguire ogni comando.

Aprire la directory del progetto

Se hai una directory preferita per il progetto, aprila nell'IDE. Puoi anche chiedere a Bob di farlo nella finestra di chat.

Configurare un ambiente virtuale Python

È prassi comune creare ambienti virtuali Python per isolare le dipendenze di un progetto ed evitare conflitti tra progetti diversi. Passa Bob alla modalità Agent, quella che può leggere, scrivere ed eseguire comandi di terminale, poi crea l'ambiente.

Creare e attivare l'ambiente virtuale

Nel pannello di chat di Bob, inserisci il seguente prompt:

In this directory, activate a Python virtual environment.

Bob esegue una serie di comandi di terminale. Approva ognuno quando richiesto. I comandi creano un nuovo ambiente virtuale nella directory venv/ e lo attivano.

Generare il piano di costruzione del server MCP

Passare alla modalità Plan

Clicca sul pulsante appena sotto il campo di input della chat per cambiare la modalità di interazione in Plan. Questa modalità consente a Bob di generare un piano strutturato per il server MCP prima di scrivere qualsiasi codice.

Inviare i requisiti del server

Con l'ambiente virtuale attivo, invia il seguente prompt a Bob. Fornire requisiti specifici fin dall'inizio dà a Bob abbastanza contesto per formulare un piano completo prima di scrivere codice:

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

Bob produce un elenco di attività strutturato che copre il scaffolding del progetto, l'implementazione del server MCP, l'installazione delle dipendenze, la configurazione del server e i test. Nota che Bob pianifica automaticamente la gestione degli errori e le considerazioni sull'autenticazione. Anche quando l'API di destinazione (arXiv) non richiede una chiave, Bob indica dove verrebbero iniettate le credenziali per i server che ne hanno bisogno.

Se Bob fa domande di chiarimento, rispondi nel modo migliore possibile o di' a Bob di fare assunzioni ragionevoli.

Creare e rivedere il server MCP

Una volta verificato e approvato il piano, passa alla modalità Agent per eseguire ogni passaggio. Il tuo output e l'ordine potrebbero variare leggermente dall'esempio seguente, poiché Bob genera le risposte in tempo reale.

Di' a Bob di iniziare a costruire il server con il seguente prompt:

Implement the plan.

Prima di tutto, Bob crea l'impalcatura della struttura del progetto ed esegue mkdir -p arxiv-server/src per creare la directory del progetto.

Successivamente, Bob genera arxiv-server/package.json, il hub di configurazione di Node.js che dichiara i metadati, gli script e le dipendenze del progetto:

{
  "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"
  }
}

Bob crea anche arxiv-server/tsconfig.json per configurare il compilatore 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"]
}

Successivamente, Bob crea il file principale del server in arxiv-server/src/index.ts. Questo file registra lo strumento search_arxiv con l'MCP SDK, implementa il parsing da XML a JSON per le risposte dell'API arXiv, applica i limiti ai risultati e avvia il server sul trasporto STDIO — il tipo di trasporto locale a bassa latenza adatto ai server in esecuzione sulla stessa macchina dell'host MCP.

La chiamata server.tool() dell'MCP SDK è il punto di integrazione principale. Espone lo strumento a qualsiasi client 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');

Il flag isError: true nel blocco catch è il pattern standard di gestione degli errori MCP. Segnala al client MCP che la chiamata allo strumento è fallita senza terminare il processo del server.

Come passaggio successivo, Bob installa le dipendenze nella directory arxiv-server eseguendo cd arxiv-server && npm install.

Registrare il server nell'ambito del progetto

Bob non registra automaticamente un nuovo server. Di' a Bob di aggiungerlo esplicitamente, specificando l'ambito del progetto in modo che la configurazione sia in .bob/mcp.json e possa essere condivisa con il tuo team tramite il controllo di versione.

Dire a Bob di registrare il server

Nel pannello di chat di Bob, inserisci il seguente prompt:

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

Rivedere la configurazione generata

Bob scrive quanto segue in .bob/mcp.json nella radice del tuo progetto. I campi command e args indicano al client MCP come avviare il processo del server usando il trasporto STDIO.

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

Confermare che il server è caricato

Bob ricarica automaticamente la configurazione MCP dopo aver scritto questo file. Apri il pannello delle impostazioni MCP (icona a ingranaggio > MCP) per confermare che il server arxiv-server sia elencato e abilitato prima di continuare. Se non appare, clicca sull'icona di ricaricamento accanto all'elenco dei server.

Riavviare Bob

Riavvia Bob per assicurarti che il server sia in esecuzione e pronto ad accettare query.

Testare il server MCP

Con il server registrato, Bob esegue automaticamente due query di validazione contro lo strumento search_arxiv.

La prima query cerca tre articoli di quantum computing ordinati per rilevanza. La seconda cerca due articoli di machine learning ordinati per data di invio decrescente. Entrambe vengono eseguite con successo, confermando che lo strumento è raggiungibile e che la gestione degli errori del server gestisce correttamente diverse combinazioni di parametri.

Esegui ora le tue query per verificare che Bob estragga i parametri corretti dal linguaggio naturale. Un esempio di prompt da incollare nel pannello di chat di Bob:

What are the latest papers on LLM agent tracing?

Documentare il server

Le implementazioni di server MCP open source in genere includono documentazione per permettere agli altri di iniziare rapidamente. Chiedi a Bob di generarla:

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

Bob produce un README.md completo che copre l'installazione, la configurazione per più host MCP (IBM Bob, Claude Desktop, Cursor, Claude Code), indicazioni sull'autenticazione per i server che richiedono chiavi API, pattern di accesso ai file locali e suggerimenti per la risoluzione dei problemi.

Pulizia delle risorse

Questo tutorial crea file locali e una registrazione del server. Rimuovili se non prevedi di continuare a usare il server MCP arXiv.

Apri il pannello delle impostazioni MCP in Bob (icona a ingranaggio > MCP) e disabilita o elimina la voce arxiv-server. In alternativa, rimuovi direttamente il blocco arxiv-server da mcp_settings.json (ambito globale) o da .bob/mcp.json (ambito progetto).

Passaggi successivi

In questo tutorial, hai usato IBM Bob per creare un server MCP TypeScript, configurarlo con il trasporto STDIO e testarlo con query live su arXiv, il tutto tramite prompt in linguaggio naturale.

Lo stesso workflow si applica a implementazioni di server MCP più complesse: server che si connettono a database, file locali o qualsiasi altra fonte di dati esterna. I server che richiedono autenticazione hanno bisogno di credenziali iniettate come variabili d'ambiente nel JSON di configurazione MCP. Per i deployment remoti, sostituisci il trasporto STDIO con SSE.

Scopri la funzionalità di code review di Bob per individuare i problemi prima di fare il commit del codice del server.

Scopri le modalità per capire quando usare Advanced, Code, Ask e le altre personas di Bob.

Esplora la configurazione MCP per dettagli sull'ambito globale vs. di progetto, gli strumenti approvati automaticamente e la configurazione del trasporto SSE.

Lavora sulla serie di tutorial introduttivi a IBM Bob per continuare ad imparare.

Creare server MCP con IBM Bob