Ir al contenido principal
Español— Elegir un idioma
Menú

Tu primer plugin

Lección 4 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Dos pasos
  2. Paso 1: Un plugin personal en cinco minutos
  3. Paso 2: Tu propio servidor
  4. Recargar tras cada cambio
  5. Puntos clave

Lección reescrita el 3 de noviembre de 2026 basándose en las páginas Quickstart, MCP server and UI quickstart y Connect and test your plugin de la documentación de Plugins de OpenAI. El ejemplo anterior de «aplicación meteorológica en 30 minutos» dependía de un SDK inexistente. Verificamos las versiones de los paquetes npm el 3 de noviembre de 2026: @modelcontextprotocol/ext-apps 2.x se basa en el SDK MCP v2, mientras que los ejemplos de OpenAI utilizan la v1. Fuentes: Quickstart · MCP server and UI quickstart · Connect and test.

Dos pasos

Primero, conectarás un servidor MCP existente para ver el flujo de trabajo completo de ChatGPT sin escribir ni una línea de código. A continuación, escribirás tu propio servidor, lo probarás localmente y lo conectarás de la misma manera.

Paso 1: Un plugin personal en cinco minutos

OpenAI ofrece un servidor MCP de ejemplo público y sin autenticación que expone una única herramienta de solo lectura: roll_dice.

  1. Ve a ChatGPT Plugins, selecciona el botón + y elige Add custom MCP server.
  2. Introduce un nombre y establece la Server URL en https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Selecciona No authentication.
  3. Lee la advertencia de riesgo, marca I understand and want to continue y haz clic en Create as a plugin.
  4. El plugin aparecerá en tu lista de plugins personales: ábrelo e instálalo usando el botón +.
  5. Vuelve a la pantalla de inicio de ChatGPT, cambia de la pestaña Chat a Work, inicia una nueva conversación, escribe @ y selecciona tu plugin.
  6. Pídele que tire un dado de veinte caras: debería llamar a roll_dice exactamente una vez con sides establecido en 20 y devolver un valor entre 1 y 20.

No te limites al camino feliz. Prueba con diferentes tamaños de dado, valores no válidos y solicitudes que no deberían activar ninguna herramienta. Este reflejo impulsa el resto del curso: cuando el modelo elige la herramienta incorrecta o varía sus argumentos, debes refinar la descripción y el esquema de la herramienta. Ten también en cuenta que las políticas de tu cuenta o espacio de trabajo rigen la adición de servidores MCP personalizados: en una organización, esta opción puede estar restringida.

Paso 2: Tu propio servidor

Instalar los SDK oficiales

Existen SDK oficiales del protocolo para TypeScript (@modelcontextprotocol/sdk) y Python (mcp). Este curso sigue los ejemplos de OpenAI, escritos en TypeScript utilizando el SDK v1. Fija tus versiones: a fecha de septiembre de 2026, @modelcontextprotocol/ext-apps 2.x —el paquete de interfaz que añadirás en la Lección 6— depende de los nuevos paquetes del SDK v2 (@modelcontextprotocol/server…), que son incompatibles con las importaciones de la v1.

mkdir notes-plugin && cd notes-plugin
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk@^1.29 @modelcontextprotocol/ext-apps@^1.7 zod

npm pkg set type=module añade "type": "module" a package.json, algo necesario para las sentencias import del servidor.

Escribir el servidor

Este servidor cabe en un único archivo, server.js. Mantiene las notas en memoria y expone dos herramientas: una para leer y otra para escribir, separadas como se recomienda en la Lección 3.

import { createServer } from "node:http";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const notes = []; // ejemplo de datos en memoria: sustituye por tu propio almacenamiento
const schemaNotes = {
  notes: z.array(z.object({ id: z.string(), text: z.string() })),
};

function creerServeur() {
  const server = new McpServer({ name: "notes-demo", version: "0.1.0" });

  server.registerTool(
    "list_notes",
    {
      title: "List notes",
      description: "Use when the user wants to review notes saved with this plugin.",
      inputSchema: {},
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    },
    async () => ({
      structuredContent: { notes },
      content: [{ type: "text", text: `${notes.length} note(s) saved.` }],
    })
  );

  server.registerTool(
    "add_note",
    {
      title: "Add a note",
      description: "Use when the user asks to save a short note.",
      inputSchema: { text: z.string().min(1).max(500) },
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
    },
    async ({ text }) => {
      notes.push({ id: `note-${notes.length + 1}`, text });
      return {
        structuredContent: { notes },
        content: [{ type: "text", text: "Note saved." }],
      };
    }
  );

  return server;
}

const PORT = Number(process.env.PORT ?? 8787);

createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
  if (url.pathname !== "/mcp") {
    res.writeHead(404).end("Not Found");
    return;
  }

  // Modo sin estado: nuevo servidor y transporte por solicitud
  const server = creerServeur();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on("close", () => {
    transport.close();
    server.close();
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req, res);
  } catch (error) {
    console.error("MCP Error:", error);
    if (!res.headersSent) res.writeHead(500).end("Internal server error");
  }
}).listen(PORT, () => console.log(`MCP server ready on http://localhost:${PORT}/mcp`));

Tres detalles son cruciales. Cada herramienta declara un título, una descripción de la intención, esquemas y anotaciones exactas: este es su «perfil» para el modelo. Cada resultado combina structuredContent, reutilizable por el modelo, y content, un breve mensaje de texto. Por último, cualquier dirección distinta de /mcp devuelve un 404: el ejemplo de OpenAI hace esto para las rutas de descubrimiento de OAuth que aún no estás utilizando, evitando que ChatGPT muestre errores 502 durante tus pruebas sin autenticación. Ese mismo ejemplo añade una respuesta para la solicitud CORS preliminar (OPTIONS) y un GET / para sondeos de estado; inclúyelos si tu alojamiento los espera.

Probar localmente con MCP Inspector

node server.js
npx @modelcontextprotocol/inspector@latest

En el Inspector, elige Streamable HTTP, introduce http://localhost:8787/mcp y conéctate. Verifica que la inicialización se realiza correctamente, que ambas herramientas aparecen con sus esquemas y anotaciones, y luego llámalas con entradas válidas y no válidas: una cadena de texto vacía debe ser rechazada por el esquema.

Exponer el servidor y conectarlo

ChatGPT debe poder alcanzar tu servidor desde internet. Durante el desarrollo, un túnel es suficiente; la documentación cita ngrok:

ngrok http 8787

Obtendrás una dirección HTTPS pública. Conéctala como en el Paso 1, incluyendo la ruta /mcp (por ejemplo https://<subdomain>.ngrok.app/mcp), instala el plugin resultante e invócalo con @: «Guarda una nota: llama al proveedor el lunes». ChatGPT muestra los datos intercambiados con la herramienta, lo que te permite verificar las entradas y salidas.

Un túnel de desarrollo solo sirve para pruebas: la publicación requiere un punto final HTTPS público y estable (Lección 5).

Recargar tras cada cambio

ChatGPT almacena en caché los metadatos de tu servidor. Tras cualquier cambio en el nombre, la descripción, el esquema, la anotación, la autenticación o el recurso de interfaz: vuelve a desplegar o reinicia el servidor, abre la conexión en chatgpt.com/plugins, selecciona Refresh, verifica que los metadatos anunciados han cambiado y, a continuación, abre una nueva conversación para volver a ejecutar tus pruebas. Omitir este paso significa probar la versión antigua sin darte cuenta.

Puntos clave

  • Crea un plugin personal mediante Add custom MCP server e invócalo con @ en ChatGPT
  • SDK oficiales: @modelcontextprotocol/sdk (TypeScript) y mcp (Python); fija la v1 con ext-apps 1.x para seguir los ejemplos de OpenAI
  • Servidor mínimo: McpServer, registerTool, transporte streamable HTTP en /mcp
  • Usa MCP Inspector para pruebas locales y un túnel para pruebas en ChatGPT
  • Tras cualquier cambio en los metadatos: Refresh y luego inicia una nueva conversación