Aprende a usar IBM Bob para crear un servidor personalizado de Model Context Protocol (MCP) que conecta modelos de IA con herramientas externas y fuentes de datos. Cubre el modo avanzado, el flujo de aprobación y la configuración de MCP en este tutorial práctico.

En este tutorial, usas IBM Bob para crear un servidor MCP personalizado que ofrece acceso de solo lectura a arXiv, un repositorio de contenido de acceso abierto para artículos científicos. Opcionalmente, puedes extender el servidor para integrarlo con un agente de IA de watsonx Orchestrate.

El Model Context Protocol (MCP) es un estándar abierto que permite a los grandes modelos de lenguaje (LLMs) comunicarse con herramientas externas, fuentes de datos y repositorios de contenido a través de una arquitectura cliente-servidor unificada. Antes de MCP, cada asistente de IA necesitaba su propia integración para cada herramienta externa, usando function calling sin interoperabilidad. En cambio, MCP define un único protocolo JSON-RPC 2.0 que cualquier host MCP puede usar para conectarse a cualquier servidor MCP.

Prerrequisitos

Este tutorial crea un servidor MCP en TypeScript que consulta la API de arXiv. No se requiere experiencia previa en TypeScript ni en integración MCP.

Para completar este tutorial, necesitas lo siguiente:

IBM Bob IDE

Descarga e instala la aplicación IBM Bob en tu computadora. Bob es una aplicación IDE independiente, no una extensión.

Node.js

Instala Node.js 22 o posterior para crear y ejecutar el servidor MCP de TypeScript localmente.

Configurar tu workspace

Inicia IBM Bob, abre el panel de configuración de MCP y prepara un directorio de trabajo para el proyecto del servidor.

Iniciar IBM Bob

Inicia la aplicación IBM Bob en tu computadora.

Abrir el panel de chat de Bob

Si el panel de chat no está abierto, haz clic en el icono de Bob junto a la barra de navegación o usa el atajo Option + Command + B (Mac) o Ctrl + Alt + B (Windows).

Abrir el panel de configuración de MCP

Haz clic en el icono de engranaje en la esquina superior derecha de la ventana de chat y selecciona MCP en la barra lateral izquierda.

El panel de configuración de MCP te permite gestionar el control de acceso habilitando o deshabilitando servidores, aprobando automáticamente herramientas específicas, y crear integraciones personalizadas con el MCP SDK.

Global: Almacenado en mcp_settings.json, aplicado en todos los workspaces.
Proyecto: Almacenado en .bob/mcp.json en la raíz del proyecto, se puede compartir con tu equipo a través del control de versiones. La configuración a nivel de proyecto anula la global.

Configurar la aprobación automática

En el chat de Bob, asegúrate de que los permisos de aprobación automática justo debajo del campo de entrada del chat estén configurados solo en "Read" (Leer). Esta configuración permite a Bob ver tus archivos y el contenido del directorio, mientras solicita tu revisión y aprobación antes de ejecutar cada comando.

Abrir tu directorio de proyecto

Si tienes un directorio preferido para el proyecto, ábrelo en el IDE. También puedes pedirle a Bob que lo haga en la ventana de chat.

Configurar un entorno virtual de Python

Es práctica común crear entornos virtuales de Python para aislar las dependencias de un proyecto y evitar conflictos entre proyectos. Cambia Bob al modo Agent, el modo que puede leer, escribir y ejecutar comandos de terminal, y luego crea el entorno.

Crear y activar el entorno virtual

En el panel de chat de Bob, introduce el siguiente prompt:

In this directory, activate a Python virtual environment.

Bob ejecuta una serie de comandos de terminal. Aprueba cada uno cuando se te solicite. Los comandos crean un nuevo entorno virtual en el directorio venv/ y lo activan.

Generar el plan de construcción del servidor MCP

Cambiar al modo Plan

Haz clic en el botón justo debajo del campo de entrada del chat para cambiar el modo de interacción a Plan. Este modo permite a Bob generar un plan estructurado para el servidor MCP antes de escribir código.

Enviar los requisitos del servidor

Con el entorno virtual activo, envía el siguiente prompt a Bob. Proporcionar requisitos específicos desde el principio le da a Bob suficiente contexto para formular un plan completo antes de escribir 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

Bob produce una lista de tareas estructurada que cubre el scaffolding del proyecto, la implementación del servidor MCP, la instalación de dependencias, la configuración del servidor y las pruebas. Observa que Bob planifica automáticamente el manejo de errores y las consideraciones de autenticación. Aunque la API de destino (arXiv) no requiere una clave, Bob indica dónde se inyectarían las credenciales para servidores que sí la requieren.

Si Bob hace preguntas aclaratorias, respóndelas lo mejor que puedas o dile a Bob que haga suposiciones razonables.

Crear y revisar el servidor MCP

Una vez que revises y apruebes el plan, cambia al modo Agent para ejecutar cada paso. Tu resultado y el orden pueden variar ligeramente respecto al siguiente ejemplo, ya que Bob genera respuestas en tiempo real.

Dile a Bob que comience a construir el servidor con el siguiente prompt:

Implement the plan.

Primero, Bob crea el andamiaje de la estructura del proyecto y ejecuta mkdir -p arxiv-server/src para crear el directorio del proyecto.

A continuación, Bob genera arxiv-server/package.json, el hub de configuración de Node.js que declara los metadatos, scripts y dependencias del proyecto:

{
  "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 también crea arxiv-server/tsconfig.json para configurar el compilador de 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"]
}

A continuación, Bob crea el archivo principal del servidor en arxiv-server/src/index.ts. Este archivo registra la herramienta search_arxiv con el MCP SDK, implementa el análisis XML a JSON para las respuestas de la API de arXiv, aplica límites de resultados e inicia el servidor en el transporte STDIO, el tipo de transporte local y de baja latencia adecuado para servidores que se ejecutan en la misma máquina que el host MCP.

La llamada server.tool() del MCP SDK es el punto de integración principal. Expone la herramienta a cualquier 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');

El flag isError: true en el bloque catch es el patrón estándar de manejo de errores de MCP. Indica al cliente MCP que la llamada a la herramienta falló sin detener el proceso del servidor.

Como siguiente paso, Bob instala las dependencias dentro del directorio arxiv-server ejecutando cd arxiv-server && npm install.

Registrar el servidor en el ámbito del proyecto

Bob no registra un nuevo servidor automáticamente. Dile a Bob que lo añada explícitamente y especifica el ámbito del proyecto para que la configuración se guarde en .bob/mcp.json y pueda compartirse con tu equipo a través del control de versiones.

Decirle a Bob que registre el servidor

En el panel de chat de Bob, introduce el siguiente 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 la configuración generada

Bob escribe lo siguiente en .bob/mcp.json en la raíz de tu proyecto. Los campos command y args le dicen al cliente MCP cómo iniciar el proceso del servidor usando el transporte STDIO.

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

Confirmar que el servidor está cargado

Bob recarga la configuración MCP automáticamente después de escribir este archivo. Abre el panel de configuración de MCP (icono de engranaje > MCP) para confirmar que el servidor arxiv-server está listado y habilitado antes de continuar. Si no aparece, haz clic en el icono de recarga junto a la lista de servidores.

Reiniciar Bob

Reinicia Bob para asegurarte de que el servidor esté en ejecución y listo para aceptar consultas.

Probar el servidor MCP

Con el servidor registrado, Bob ejecuta automáticamente dos consultas de validación contra la herramienta search_arxiv.

La primera consulta busca tres artículos de computación cuántica ordenados por relevancia. La segunda busca dos artículos de machine learning ordenados por fecha de envío descendente. Ambas se ejecutan correctamente, confirmando que la herramienta es accesible y que el manejo de errores del servidor gestiona correctamente diferentes combinaciones de parámetros.

Ahora ejecuta tus propias consultas para verificar que Bob extrae los parámetros correctos del lenguaje natural. Un ejemplo de prompt para pegar en el panel de chat de Bob:

What are the latest papers on LLM agent tracing?

Documentar el servidor

Las implementaciones de servidores MCP de código abierto suelen incluir documentación para que otros puedan empezar rápidamente. Pídele a Bob que la genere:

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

Bob produce un README.md completo que cubre la instalación, la configuración para varios hosts MCP (IBM Bob, Claude Desktop, Cursor, Claude Code), orientación sobre autenticación para servidores que requieren claves de API, patrones de acceso a archivos locales y consejos para solución de problemas.

Limpiar recursos

Este tutorial crea archivos locales y un registro de servidor. Elimínalos si no planeas seguir usando el servidor MCP de arXiv.

Abre el panel de configuración de MCP en Bob (icono de engranaje > MCP) y deshabilita o elimina la entrada arxiv-server. Alternativamente, elimina el bloque arxiv-server directamente de mcp_settings.json (ámbito global) o .bob/mcp.json (ámbito de proyecto).

Pasos siguientes

En este tutorial, usaste IBM Bob para crear un servidor MCP en TypeScript, configurarlo con transporte STDIO y probarlo con consultas en vivo a arXiv, todo mediante prompts en lenguaje natural.

El mismo flujo de trabajo se aplica a implementaciones de servidores MCP más complejas: servidores que se conectan a bases de datos, archivos locales u otras fuentes de datos externas. Los servidores que requieren autenticación necesitan credenciales inyectadas como variables de entorno en el JSON de configuración de MCP. Para despliegues remotos, reemplaza el transporte STDIO por SSE.

Aprende sobre la función de revisión de código de Bob para detectar problemas antes de hacer commit del código del servidor.

Aprende sobre los modos para entender cuándo usar Advanced, Code, Ask y otras personas de Bob.

Explora la configuración de MCP para obtener detalles sobre el ámbito global vs. de proyecto, herramientas aprobadas automáticamente y configuración del transporte SSE.

Trabaja en la serie de tutoriales de introducción a IBM Bob para seguir aprendiendo.

Crear servidores MCP con IBM Bob