Crear un servidor MCP

Agrega un servidor MCP cuando un caso de uso de un complemento necesite datos en tiempo real, autenticación, acciones controladas o código que se ejecute en infraestructura que tú operas. El servidor define las herramientas disponibles para ChatGPT y Codex. No necesita devolver una interfaz personalizada.

Parte de los objetivos contemplados en tu inventario de casos de uso. Cada herramienta debe ayudar a cumplir un objetivo identificable del usuario y exponer solo los datos y las acciones necesarios para ese objetivo.

Elegir un kit de desarrollo de software de MCP

Los kits de desarrollo de software oficiales proporcionan utilidades para esquemas, una estructura base para el servidor y transporte HTTP con streaming:

• SDK de TypeScript, publicado como @modelcontextprotocol/sdk.
• SDK de Python, publicado como mcp.

Instala el SDK que corresponda al stack de tu servidor:

# TypeScript
npm install @modelcontextprotocol/sdk zod

# Python
pip install mcp

Crear el servidor

Crea un servidor MCP con un nombre y una versión estables:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "acme-projects",
  version: "1.0.0",
});

Los servidores MCP también pueden devolver un campo instructions durante la inicialización. ChatGPT y Codex usan estas instrucciones junto con los metadatos de las herramientas.

Usa las instrucciones del servidor para dar indicaciones que se apliquen a varias herramientas, como secuencias obligatorias de herramientas o límites de solicitudes compartidos. Coloca los detalles más importantes en los primeros 512 caracteres. No repitas la descripción de cada herramienta ni intentes cambiar la personalidad del modelo.

const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before updating a project, call get_project to confirm its ID and current status.",
  }
);

Definir herramientas a partir de los objetivos del usuario

Crea una herramienta para cada acción distinta que el complemento deba admitir. Prioriza operaciones específicas como list_projects, get_project y update_project frente a una sola herramienta con muchos modos sin relación entre sí.

Cada herramienta necesita:

• Un nombre orientado a la acción y un título comprensible para las personas.
• Una descripción que explique cuándo usarla.
• Un esquema de entrada explícito.
• Un esquema de salida cuando la herramienta devuelva datos estructurados.
• Anotaciones de seguridad precisas.
• Un manejador que autorice la solicitud y realice la operación.

El modelo usa estos metadatos para decidir si debe llamar a la herramienta y cómo hacerlo. Considera los nombres, las descripciones, los esquemas y las anotaciones como parte del comportamiento del complemento que percibe el usuario.

import { z } from "zod";

server.registerTool(
  "list_projects",
  {
    title: "List projects",
    description:
      "Use this when the user wants to find or review projects in their Acme workspace.",
    inputSchema: {
      status: z.enum(["active", "archived"]).optional(),
    },
    outputSchema: {
      projects: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          status: z.string(),
        })
      ),
    },
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
      destructiveHint: false,
    },
  },
  async ({ status }) => {
    const projects = await listProjects({ status });

    return {
      structuredContent: { projects },
      content: [
        {
          type: "text",
          text: `Found ${projects.length} projects.`,
        },
      ],
    };
  }
);

Devolver resultados útiles sin una interfaz

El resultado de una herramienta puede incluir:

• structuredContent: datos concisos que el modelo puede examinar y usar en llamadas posteriores.
• content: texto u otro contenido de MCP que ayude al modelo a responder al usuario.
• _meta: datos específicos del cliente que están ocultos para el modelo.

Devuelve información suficiente para que el modelo complete el flujo de trabajo sin un componente. Usa identificadores estables en los resultados estructurados para que las herramientas que se usen después puedan hacer referencia a los mismos registros.

No incluyas secretos, tokens de acceso ni datos personales innecesarios en los resultados de las herramientas. Considera _meta como información oculta para el modelo, no como un sustituto de la autorización o el almacenamiento seguro.

Importar habilidades desde el servidor MCP

Configura el servidor MCP para que proporcione habilidades cuando quieras versionar y desplegar sus instrucciones y archivos de apoyo junto con el servidor. Durante el envío del complemento, Escanear herramientas importa una instantánea estática de esas habilidades al borrador.

Actualmente, OpenAI admite un subconjunto limitado y estático del borrador de la extensión de habilidades SEP-2640. Esta propuesta aún no forma parte de la especificación estable de MCP.

Anunciar la extensión

Declara io.modelcontextprotocol/skills en las capacidades de inicialización del servidor:

{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/skills": {}
    }
  }
}

La declaración debe estar dentro de capabilities.extensions. OpenAI no reconoce la declaración anterior en experimental.

Enumerar las habilidades y sus recursos

Implementa el método paginado skills/list. Cada entrada debe incluir:

• Un uri que apunte al SKILL.md de la habilidad.
• frontmatter con todas las entradas obtenidas al analizar los metadatos de cabecera de SKILL.md. Incluye las entradas name y description.
• Una lista resources completa que contenga SKILL.md y todos los archivos de apoyo.
• Un hash SHA-256 para cada recurso con el formato sha256:<64 lowercase hexadecimal characters>.

Usa la convención de URI skill://. El directorio que contiene SKILL.md debe tener el mismo nombre que la habilidad. Por ejemplo:

{
  "skills": [
    {
      "uri": "skill://dice-roller/tabletop-dice/SKILL.md",
      "frontmatter": {
        "name": "tabletop-dice",
        "description": "Roll one or more dice and report each result and the total."
      },
      "resources": [
        {
          "uri": "skill://dice-roller/tabletop-dice/SKILL.md",
          "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
        },
        {
          "uri": "skill://dice-roller/tabletop-dice/references/notation.md",
          "digest": "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        }
      ]
    }
  ],
  "nextCursor": "optional-next-page-cursor"
}

Los hashes del ejemplo muestran el formato requerido. Para un recurso de texto, calcula el hash de los bytes UTF-8 de content.text. Para un recurso blob, decodifica de base64 content.blob y luego calcula el hash de los bytes decodificados.

Implementa también skills/get para cada URI de SKILL.md incluido en la lista. Devuelve un objeto skill con la misma estructura de entrada completa que skills/list.

Usa estos parámetros de solicitud:

• Para la primera solicitud a skills/list, acepta un objeto vacío ({}).
• Para cada solicitud posterior a skills/list, acepta el cursor devuelto, por ejemplo: { "cursor": "next-page-cursor" }.
• Para skills/get, acepta el URI del catálogo, por ejemplo: { "uri": "skill://dice-roller/tabletop-dice/SKILL.md" }.

Devolver todos los recursos enumerados

Implementa resources/read para cada URI del archivo de manifiesto. Devuelve exactamente un elemento de contenido cuyo URI coincida con el de la solicitud. OpenAI acepta texto UTF-8 o un blob codificado en base64.

Durante la importación, OpenAI verifica que:

• OpenAI pueda obtener cada recurso enumerado y confirmar su hash.
• Los metadatos de cabecera del SKILL.md obtenido coincidan exactamente con la entrada del catálogo.
• Las rutas de los recursos sean seguras, únicas y no presenten conflictos de normalización.
• La habilidad completa se ajuste a los límites de importación.

El importador acepta hasta cinco habilidades con nombres únicos distribuidas en 10 páginas de catálogo. Cada habilidad puede contener hasta 100 archivos, con estos límites de tamaño:

El límite combinado de los archivos comprimidos incluye el espacio adicional del empaquetado ZIP.

Si alguna entrada no pasa la validación o supera un límite, Analizar herramientas sigue devolviendo las herramientas del servidor, pero no actualiza las habilidades importadas del borrador. Corrige el servidor y vuelve a ejecutar el análisis.

Las habilidades importadas desde MCP son instantáneas del momento del envío, no recursos que se consultan en vivo durante la ejecución. Después de modificar una habilidad, ejecuta Analizar herramientas de nuevo, revisa las habilidades importadas y envía una nueva versión del complemento. Consulta Enviar complementos para conocer el flujo completo.

Autenticar y autorizar solicitudes

Agrega autenticación cuando una herramienta lea datos privados o realice acciones en nombre de un usuario. Aplica controles de autorización en el servidor MCP para cada solicitud; nunca dependas del modelo para decidir si un usuario tiene acceso.

Consulta Autenticar usuarios para obtener información sobre el descubrimiento de OAuth, los esquemas de seguridad y los desafíos de autorización.

Para mejorar la experiencia al usar varias cuentas, expón una herramienta de perfil que requiera autenticación y sea de solo lectura, y márcala con _meta["openai/profile"]: true. OpenAI usa la información del perfil para identificar las cuentas conectadas de forma consistente y ayudar a los usuarios a distinguirlas. Obtén el perfil a partir de las credenciales validadas de la solicitud y limita el alcance de cada llamada a herramientas a esas credenciales. Los usuarios pueden conectar varias cuentas sin una herramienta de perfil. Consulta Admitir varias cuentas para ver el esquema y el ejemplo de implementación.

Anotaciones de herramientas y exploración

Configura las anotaciones según el comportamiento real:

• readOnlyHint: true solo cuando la herramienta no pueda modificar el estado.
• destructiveHint: true cuando una herramienta pueda causar resultados irreversibles o difíciles de revertir.
• openWorldHint: true cuando una herramienta acceda a la internet pública o a entidades externas sin un alcance delimitado, incluso mediante acciones de solo lectura, como la búsqueda web. Una herramienta limitada a una cuenta privada o un espacio de trabajo de alcance delimitado puede establecer este valor en false, incluso si el servicio está alojado externamente.

Las anotaciones ayudan a ChatGPT y Codex a elegir el comportamiento adecuado en materia de confirmación y seguridad. No reemplazan la autorización, la validación ni la confirmación en tu servidor.

Usa la exploración de MCP cuando el servidor necesite información estructurada que no se haya proporcionado en la llamada original a la herramienta. Limita la exploración a información que sea razonable pedirle al usuario. No la uses para recopilar secretos ni eludir la autenticación habitual.

Compatibilidad con el conocimiento de la empresa

El conocimiento de la empresa puede usar herramientas de solo lectura de tu servidor MCP. Para que un complemento pueda utilizarse como fuente de conocimiento de la empresa, implementa los esquemas de entrada estándar de las herramientas search y fetch, y marca las demás herramientas de solo lectura con readOnlyHint: true.

Devuelve URL absolutas que el usuario pueda abrir para las fuentes que el modelo deba citar. Mantén los identificadores internos de los documentos en el campo id del resultado. Para conocer los esquemas y las estructuras de resultados requeridos, consulta Crear servidores MCP para ChatGPT e integraciones de API.

Ejecutar y probar localmente

Expón un punto de acceso HTTP con transmisión continua, por lo general en /mcp, y luego inspecciónalo con MCP Inspector:

npx @modelcontextprotocol/inspector

En la interfaz de Inspector, selecciona Streamable HTTP e ingresa http://localhost:3000/mcp.

Usa el inspector para:

1. Confirmar que la inicialización se complete correctamente.
2. Revisar las instrucciones del servidor y la lista de herramientas que anuncia.
3. Llamar a cada herramienta con entradas representativas y no válidas.
4. Verificar los esquemas, los resultados, los errores y las anotaciones.
5. Confirmar que se apliquen los controles de autorización para los datos privados y las acciones de escritura.

Luego, conecta el servidor a ChatGPT en modo de desarrollador y ejecuta las solicitudes directas, indirectas, de casos límite y fuera de alcance de tu inventario de casos de uso.

Desplegar el punto de acceso

Para enviar un complemento para su publicación, despliega el servidor MCP en un punto de acceso HTTPS estable y accesible públicamente. El Túnel MCP seguro permite conectar un servidor MCP privado en modo de desarrollador, pero no cumple los requisitos de envío para publicación.

El punto de acceso de producción debe:

• Ser compatible con el transporte HTTP con transmisión continua de MCP.
• Responder en una URL estable, que por lo general termine en /mcp.
• Cumplir con las necesidades de latencia y disponibilidad de los flujos de trabajo del complemento.
• Tener acceso a los servicios y almacenes de datos necesarios.
• Mantener los límites de autenticación y autorización.
• Generar registros y métricas de los fallos de inicialización y de las llamadas a herramientas.

Si el servidor MCP debe permanecer privado, despliega un proxy HTTPS público que reenvíe las solicitudes MCP al servidor privado. Usa mTLS administrado por OpenAI para autenticar a ChatGPT como cliente MCP y usa OAuth 2.1 cuando tu complemento requiera autenticar al usuario. Si tu red requiere una lista de direcciones IP permitidas, usa los rangos de IP de los conectores de ChatGPT publicados y actualiza la lista automáticamente. Una lista de direcciones IP permitidas no reemplaza la autenticación ni la autorización.

El punto de acceso público debe permanecer accesible para la revisión del complemento y la verificación del dominio. No uses únicamente el Túnel MCP seguro, un túnel temporal ni un punto de acceso local para enviar el complemento para su publicación.

Elegir la infraestructura

Puedes desplegar el servidor MCP en infraestructura sin servidor, de contenedores, perimetral o tradicional para aplicaciones. Elige una plataforma según:

• La compatibilidad con el entorno de ejecución y las dependencias.
• El comportamiento de las respuestas con transmisión continua.
• La latencia del arranque en frío y de las solicitudes.
• El acceso por red a los servicios necesarios.
• Los requisitos de residencia de datos y cumplimiento.
• La gestión de secretos.
• El registro de eventos, el seguimiento de trazas y las alertas.
• La compatibilidad con la reversión y el control de versiones.

Si el servidor también aloja recursos opcionales de interfaz de usuario, despliega esos recursos en orígenes estables permitidos por la política de seguridad de contenido del componente.

Configurar el punto de acceso de producción

Antes del despliegue:

1. Configura las credenciales de producción mediante el sistema de gestión de secretos del host.
2. Configura el servidor de autorización y el comportamiento de redirección permitido.
3. Aplica tiempos de espera y límites de solicitudes a las herramientas que consuman muchos recursos o sean visibles externamente.
4. Elimina las respuestas de depuración y los datos personales innecesarios.
5. Confirma que los registros no contengan tokens de acceso ni resultados de herramientas con información sensible.

Después del despliegue, llama al punto de acceso de producción con MCP Inspector. Verifica la inicialización, las instrucciones del servidor, las herramientas, los esquemas, las anotaciones, la autenticación, los resultados y los errores.

Planificar las actualizaciones

Mantén la compatibilidad con versiones anteriores de los nombres y esquemas de las herramientas publicadas. Agrega campos o herramientas sin romper los contratos existentes. Si cambian los metadatos, actualiza la conexión en modo de desarrollador y vuelve a ejecutar el conjunto de evaluaciones antes del envío.

Para la interfaz de usuario opcional, asigna versiones a los identificadores de recursos cuando los cambios en HTML, JavaScript o CSS puedan impedir que un componente almacenado en caché funcione correctamente.

Agregar una interfaz de usuario opcional

Una vez que las herramientas funcionen de principio a fin, determina si algún caso de uso necesita interacción visual. Una tabla, un mapa, un calendario editable o una vista comparativa pueden beneficiarse de una interfaz de usuario. Una consulta, una comprobación de estado o una acción en segundo plano a menudo no la necesitan.

Continúa con Agregar una interfaz de usuario a tu servidor MCP para registrar un recurso de MCP Apps y asociarlo con las herramientas seleccionadas.

Recordatorios de seguridad

• Trata todos los datos de entrada de las herramientas como datos no confiables.
• Valida los parámetros y aplica los controles de autorización en el servidor.
• Exige confirmación para las acciones de escritura con consecuencias importantes.
• Mantén los secretos y los datos sensibles fuera de los metadatos y los resultados de las herramientas.
• Registra suficiente contexto para investigar fallas sin registrar credenciales ni datos personales innecesarios.
• Aplica límites de solicitudes a las acciones costosas o visibles externamente.