Crea un servidor MCP

Agrega un servidor MCP cuando un caso de uso de tu complemento requiera datos en tiempo real, autenticación, acciones controladas o código que se ejecute en infraestructura que administras. El servidor define las herramientas disponibles para ChatGPT y Codex. No es necesario que devuelva una interfaz personalizada.

Parte de los objetivos que tu complemento admite según tu inventario de casos de uso. Cada herramienta debe ayudar al usuario a alcanzar un objetivo identificable y darle acceso solo a los datos y las acciones que necesita para lograrlo.

Elige un kit de desarrollo de software para MCP

Los kits oficiales de desarrollo de software incluyen utilidades para definir esquemas, una estructura básica para crear el servidor y un transporte HTTP que admite streaming.

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

Instala el SDK que corresponda a las tecnologías de tu servidor.

# TypeScript
npm install @modelcontextprotocol/sdk zod

# Python
pip install mcp

Crea el servidor

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

1
2
3
4
5
6import { 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 el orden en que deben llamarse o los límites de solicitudes que comparten. Incluye 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.

1
2
3
4
5
6
7const 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.",
  }
);

Define las herramientas a partir de los objetivos del usuario

Crea una herramienta para cada acción distinta que el complemento deba admitir. Da preferencia a 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 lo siguiente:

• Un nombre que indique la acción y un título fácil de entender.
• Una descripción que explique cuándo usarla.
• Un esquema de entrada explícito.
• Un esquema de salida si la herramienta devuelve datos estructurados.
• Anotaciones de seguridad que reflejen su comportamiento real.
• Una función que autorice la solicitud y ejecute 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49// Local example data; replace this with your application data.
const projects = [
  { id: "project-1", name: "Website", status: "active" },
  { id: "project-2", name: "Launch", status: "archived" },
];
async function listProjects({ status }: { status?: string }) {
  return projects.filter((project) => !status || project.status === status);
}

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.`,
        },
      ],
    };
  }
);

Devuelve resultados útiles sin una interfaz

El resultado de una herramienta puede incluir lo siguiente:

• 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 permanecen ocultos para el modelo.

Devuelve suficiente información para que el modelo pueda completar el flujo de trabajo sin un componente. Usa identificadores estables en los resultados estructurados para que otras herramientas puedan hacer referencia a los mismos registros en llamadas posteriores.

No incluyas secretos, tokens de acceso ni datos personales innecesarios en los resultados de las herramientas. El modelo no puede ver _meta, pero eso no sustituye la autorización ni el almacenamiento seguro.

Autentica y autoriza las solicitudes

Agrega autenticación cuando una herramienta lea datos privados o realice acciones en nombre de un usuario. Exige autorización para cada solicitud en el servidor MCP. Nunca delegues en el modelo la decisión de si un usuario tiene acceso.

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

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

Anotaciones de herramientas y solicitud de información

Configura las anotaciones según el comportamiento real de la herramienta.

• readOnlyHint: usa true solo si la herramienta no puede modificar el estado.
• destructiveHint: usa true si la herramienta puede tener efectos irreversibles o difíciles de revertir.
• openWorldHint: usa true si la herramienta accede a la internet pública o a un conjunto abierto de entidades externas, incluso mediante acciones de solo lectura como la búsqueda web. Si el alcance de la herramienta se limita a una cuenta privada o a un espacio de trabajo delimitado, puedes usar false aunque el servicio esté alojado externamente.

Las anotaciones ayudan a ChatGPT y Codex a elegir las medidas de confirmación y seguridad adecuadas. No sustituyen la autorización, la validación ni la confirmación en tu servidor.

Usa el mecanismo de solicitud de información de MCP cuando el servidor necesite información estructurada que no se haya incluido en la llamada original a la herramienta. Solicita solo información que el usuario pueda proporcionar razonablemente. No uses este mecanismo para recopilar secretos ni para eludir la autenticación habitual.

Compatibilidad con el conocimiento de la empresa

La función de conocimiento de la empresa puede usar herramientas de solo lectura de tu servidor MCP. Para que un complemento pueda usarse 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.

Para las fuentes que el modelo deba citar, devuelve URL absolutas que el usuario pueda abrir. Conserva los identificadores internos de los documentos en el campo id del resultado. Para conocer los esquemas y las estructuras de resultados requeridos, consulta Cómo crear servidores MCP para ChatGPT e integraciones con la API.

Ejecuta y prueba el servidor de forma local

Expón un punto de acceso HTTP que admita streaming, normalmente en /mcp, e inspecciónalo con MCP Inspector.

npx @modelcontextprotocol/inspector

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

Usa el inspector para realizar estas comprobaciones:

1. Confirma que la inicialización se complete correctamente.
2. Revisa las instrucciones del servidor y la lista de herramientas que ofrece.
3. Llama a cada herramienta tanto con entradas representativas como con entradas no válidas.
4. Verifica los esquemas, los resultados, los errores y las anotaciones.
5. Confirma que el servidor exija autorización para acceder a datos privados y realizar acciones de escritura.

Luego, conecta el servidor MCP personalizado a ChatGPT y prueba las solicitudes de tu inventario de casos de uso, incluidas las directas, las indirectas, las que cubren casos límite y las que quedan fuera del alcance.

Despliega el punto de acceso

Para enviar un complemento a revisión para su publicación, despliega el servidor MCP en un punto de acceso HTTPS estable y de acceso público. Secure MCP Tunnel permite conectar un servidor MCP privado a ChatGPT, pero por sí solo no cumple los requisitos para enviar el complemento a revisión para su publicación.

El punto de acceso de producción debe cumplir estos requisitos:

• Admitir el transporte HTTP con streaming de MCP.
• Responder en una URL estable, que normalmente termina en /mcp.
• Cumplir los requisitos de latencia y disponibilidad de los flujos de trabajo del complemento.
• Tener acceso a los servicios y almacenes de datos necesarios.
• Respetar los límites de autenticación y autorización.
• Generar registros y métricas cuando falle la inicialización o una llamada a una herramienta.

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 autenticación de usuarios. Si tu red exige una lista de direcciones IP permitidas, usa los rangos de direcciones IP publicados para los conectores de ChatGPT y actualiza la lista automáticamente. Una lista de direcciones IP permitidas no sustituye 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. Al enviar un complemento para su publicación, no uses Secure MCP Tunnel como único medio de acceso, un túnel temporal ni un punto de acceso local.

Elige la infraestructura

Puedes desplegar el servidor MCP en una infraestructura sin servidor, de contenedores, de borde o de aplicaciones tradicionales. Al elegir una plataforma, considera los siguientes criterios:

• Compatibilidad con el entorno de ejecución y las dependencias.
• Comportamiento de las respuestas en streaming.
• Latencia de los arranques en frío y de las solicitudes.
• Acceso por red a los servicios necesarios.
• Requisitos de residencia de datos y de cumplimiento normativo.
• Gestión de secretos.
• Registros, trazas y alertas.
• Compatibilidad con la reversión de despliegues y el control de versiones.

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

Configura el punto de acceso de producción

Antes del despliegue, sigue estos pasos:

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 define las redirecciones permitidas.
3. Aplica tiempos de espera máximos y límites de solicitudes a las herramientas que consuman muchos recursos o sean visibles desde el exterior.
4. Elimina las respuestas de depuración y los datos personales innecesarios.
5. Confirma que los registros no contengan tokens de acceso ni resultados sensibles de las herramientas.

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.

Planifica las actualizaciones

Mantén la compatibilidad de los nombres y esquemas de las herramientas publicadas con las versiones anteriores. Agrega campos o herramientas sin romper los contratos existentes. Si cambian los metadatos, actualiza la conexión con el servidor MCP personalizado y vuelve a ejecutar las pruebas de evaluación antes de enviar el complemento a revisión.

Si el complemento tiene una interfaz opcional, asigna una nueva versión a los identificadores de recursos cuando un cambio en el HTML, JavaScript o CSS pueda impedir que funcione un componente almacenado en caché.

Agrega extensiones de MCP

Las extensiones de MCP de OpenAI conectan tu complemento con la barra lateral, el editor y los visores de archivos de ChatGPT. Consulta Extensiones de complementos para ver ejemplos e instrucciones de configuración.

Recordatorios de seguridad

• Trata cada entrada de las herramientas como un dato no confiable.
• Valida los parámetros y exige autorización en el servidor.
• Exige confirmación para las acciones de escritura que tengan consecuencias importantes.
• No incluyas secretos ni datos sensibles en los metadatos o los resultados de las herramientas.
• Registra suficiente contexto para investigar los fallos sin incluir credenciales ni datos personales innecesarios en los registros.
• Aplica límites de solicitudes a las acciones que consuman muchos recursos o sean visibles desde el exterior.