El servidor MCP: herramientas, resultados y despliegue
En esta página
Lección reescrita el 3 de noviembre de 2026 basándose en la página Build an MCP server de la documentación de Plugins de OpenAI y en el código del SDK de TypeScript para MCP (1.32.2). La lección anterior describía «acciones» (
defineAction,ActionError) procedentes de un SDK inexistente; esta función corresponde ahora a las herramientas MCP. Fuentes: Build an MCP server · MCP TypeScript SDK.
El servidor, su identidad y sus instrucciones
Crea un servidor MCP con un nombre y una versión estables. Durante la inicialización, puede devolver también un campo instructions que ChatGPT y Codex leerán junto con los metadatos de las herramientas. Reserva este campo para directrices que se apliquen a todas las herramientas, como un orden de llamada obligatorio o un límite de tasa compartido, y mantén el contenido principal dentro de los primeros 512 caracteres. No copies y pegues aquí las descripciones de las herramientas ni intentes cambiar la personalidad del modelo.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Before modifying a project, call get_project to confirm its ID and status.",
}
);
Una herramienta por acción
Crea una herramienta para cada acción distinta: list_projects, get_project, update_project, en lugar de una única herramienta comodín con numerosos modos. Cada herramienta combina un nombre orientado a la acción, un título legible, una descripción que explica cuándo usarla, un esquema de entrada explícito, un esquema de salida si devuelve datos estructurados, anotaciones precisas y un controlador que autoriza la solicitud antes de actuar. El modelo depende de estos metadatos para decidir si debe llamar a la herramienta y cómo hacerlo; trátalo como parte de la experiencia de usuario.
import { z } from "zod";
const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });
server.registerTool(
"get_project",
{
title: "View a project",
description:
"Use when the user wants details about a specific project in their Acme workspace. " +
"Requires the ID returned by list_projects.",
inputSchema: { id: z.string().min(1) },
outputSchema: { project: project },
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async ({ id }, extra) => {
const user = await authenticate(extra); // Your access control (Lesson 8)
const found = await loadProject(user, id); // Your data access
if (!found) {
return {
isError: true,
content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
};
}
return {
structuredContent: { project: found },
content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
};
}
);
authenticate y loadProject son funciones propias. El punto crítico es su ubicación: la autorización ocurre en el servidor, con cada solicitud. No confíes nunca en que el modelo decida si un usuario tiene permiso para acceder a los datos.
Resultados útiles sin interfaz
Un resultado de herramienta puede contener tres elementos:
structuredContent: datos concisos que el modelo puede inspeccionar y reutilizar en llamadas posteriores;content: texto u otro contenido MCP que le ayude a responder;_meta: datos destinados al cliente, ocultos al modelo.
Devuelve información suficiente para que el modelo termine la tarea sin necesidad de un componente visual, utilizando IDs estables que las herramientas posteriores puedan reutilizar. Hay dos comportamientos del SDK que conviene destacar. Una herramienta que declare un outputSchema debe devolver un structuredContent conforme en todos los resultados exitosos; de lo contrario, el SDK lanzará un error de validación. Un error de negocio, como la ausencia de un proyecto o una acción denegada, se señala mediante un resultado con isError: true acompañado de texto explicativo que el modelo puede transmitir al usuario; este tipo de resultado omite la validación del esquema de salida.
No incluyas nunca secretos, tokens de acceso ni datos personales innecesarios en un resultado, y no trates _meta como un escondite seguro: este campo está oculto al modelo, pero no está protegido.
Anotaciones y elicitation
Las anotaciones deben reflejar el comportamiento real de la herramienta: establece readOnlyHint en true solo si no puede modificar nada, destructiveHint en true si puede causar un efecto irreversible o difícil de deshacer, y openWorldHint en true si toca internet público o entidades externas abiertas. Ayudan a ChatGPT y Codex a elegir el comportamiento de confirmación adecuado; no sustituyen la lógica de autorización, validación o confirmación en tu servidor.
Cuando el servidor necesite información estructurada que falte en la llamada, como una fecha o una elección entre dos opciones, puede solicitarla mediante elicitation, un mecanismo del protocolo MCP. Limita esto a lo que el usuario pueda proporcionar razonablemente; no lo uses nunca para recopilar secretos ni para eludir la autenticación normal.
Múltiples cuentas y conocimiento de la empresa
Dos compatibilidades opcionales mejoran la integración. Para ayudar a los usuarios que conectan varias cuentas, expón una herramienta de perfil que esté autenticada, sea de solo lectura y esté marcada con _meta["openai/profile"]: true. OpenAI utiliza esto para identificar las cuentas conectadas y ayudar a los usuarios a distinguirlas. El perfil se deriva de las credenciales validadas de la solicitud, y cada llamada permanece limitada a esas credenciales.
La función company knowledge de ChatGPT puede utilizar las herramientas de solo lectura de tu servidor. Para hacer que un plugin sea elegible como fuente, implementa los esquemas de entrada estándar para las herramientas search y fetch, marca otras herramientas de solo lectura con readOnlyHint: true y devuelve URLs absolutas que el usuario pueda abrir para las fuentes que el modelo deba citar.
Despliegue del endpoint
El envío público requiere un servidor en una dirección HTTPS estable y accesible públicamente. Este endpoint debe admitir el transporte streamable HTTP, responder en una URL estable (típicamente terminada en /mcp), cumplir con las demandas de latencia y disponibilidad de tus flujos de trabajo, alcanzar tus servicios y datos, preservar los límites de autenticación y autorización, y producir registros y métricas para fallos de inicialización y llamadas a herramientas.
El Secure MCP Tunnel de OpenAI permite conectar un servidor privado a ChatGPT, pero no cumple los requisitos de envío público, ni tampoco lo hace un túnel temporal o una dirección local. Si el servidor debe permanecer privado, coloca un proxy HTTPS público delante de él: mTLS gestionado por OpenAI autentica a ChatGPT como cliente, OAuth 2.1 autentica a tus usuarios, y se puede añadir una lista de permitidos de IP, incluidos los rangos publicados por OpenAI para conectores de ChatGPT, actualizados automáticamente, pero nunca debe sustituir a la autenticación.
Antes de ponerlo en producción: inyecta las credenciales mediante el gestor de secretos de tu host, configura el servidor de autorización y las redirecciones, establece tiempos de espera y límites de tasa para herramientas costosas o visibles externamente, elimina respuestas de depuración y datos personales innecesarios, y verifica que los registros no contengan tokens ni resultados sensibles. Tras el despliegue, reproduce MCP Inspector contra la dirección de producción.
Evolucionar sin romper nada
Mantén los nombres y esquemas de las herramientas publicadas compatibles con versiones anteriores: añade campos o herramientas, pero no rompas los contratos existentes. Si los metadatos cambian, actualiza la conexión y reproduce tu suite de evaluación antes de enviarla. Para una interfaz, cambia el ID del recurso cuando HTML, JavaScript o CSS evolucionen de una manera que pueda romper un componente en caché.
Recordatorios de seguridad
- Toda entrada de herramienta no es de confianza: valídala y aplica la autorización en el servidor
- Exige confirmación para escrituras de alto impacto
- Mantén los secretos y datos sensibles fuera de los metadatos y resultados
- Registra lo suficiente para investigar, pero excluye credenciales y datos personales innecesarios
- Limita la tasa de acciones costosas o visibles externamente
Puntos clave
- Un servidor con nombre y versión, con
instructionsbreves y transversales - Una herramienta por acción, con título, descripción de la intención, esquemas, anotaciones y autorización en el controlador
structuredContentconforme al esquema de salida,isError: truepara errores de negocio, nada secreto en_meta- Publicación: HTTPS estable y público mediante streamable HTTP; el Secure MCP Tunnel es insuficiente
- Contratos compatibles con versiones anteriores e IDs de recursos versionados