Crear servidores MCP para complementos e integraciones con la API

Model Context Protocol (MCP) es un protocolo abierto que se está convirtiendo en el estándar de la industria para ampliar las capacidades de los modelos de IA con herramientas y conocimientos adicionales. Los servidores MCP remotos permiten conectar los modelos por internet con nuevas fuentes de datos y capacidades.

En esta guía aprenderás a crear un servidor MCP remoto que lee datos de una fuente privada (un almacén de vectores) y permite acceder a ellos mediante un complemento en ChatGPT y Codex, mediante la investigación profunda y el conocimiento de la empresa en ChatGPT, y a través de la API.

Nota: para crear un complemento con un servidor MCP, empieza por la documentación sobre complementos: Inicio rápido, Crea tu servidor MCP, Conecta y prueba tu complemento y Autenticación. Si tu servidor MCP no necesita una interfaz de usuario, puedes exponer herramientas sin recursos de interfaz.

Configura una fuente de datos

Puedes usar datos de cualquier fuente en un servidor MCP remoto. Para simplificar el ejemplo, usaremos almacenes de vectores en la API de OpenAI. Primero, sube un documento PDF a un almacén de vectores nuevo. Puedes usar este libro de dominio público del siglo XIX sobre gatos como ejemplo.

Puedes subir archivos y crear un almacén de vectores desde el panel. También puedes crear almacenes de vectores y subir archivos mediante la API. Sigue la guía de almacenes de vectores para configurar uno y subir un archivo.

Anota el ID único del almacén de vectores para usarlo en el siguiente ejemplo.

Crea un servidor MCP

Ahora crearemos un servidor MCP remoto que hará búsquedas en nuestro almacén de vectores y podrá devolver el contenido de un documento a partir del ID del archivo.

En este ejemplo crearemos el servidor MCP con Python y FastMCP. Al final de esta sección encontrarás la implementación completa del servidor y las instrucciones para ejecutarlo en un entorno de desarrollo en el navegador.

También puedes usar otros frameworks para crear servidores MCP en distintos lenguajes de programación. Sea cual sea el framework que elijas, las definiciones de las herramientas de tu servidor deben seguir la estructura que se describe aquí.

Para que funcione con la investigación profunda y el conocimiento de la empresa en ChatGPT, tu servidor MCP debe implementar dos herramientas de solo lectura: search y fetch. Usa el esquema de compatibilidad descrito en Compatibilidad con el conocimiento de la empresa. La misma interfaz sirve para los flujos de trabajo de investigación que usan la API.

Declara un esquema de salida para cada herramienta para que los clientes puedan validar la estructura del resultado. En FastMCP, los modelos de retorno tipados pueden generar este esquema automáticamente. En el siguiente ejemplo, se pasa output_schema de forma explícita a partir de esos mismos modelos.

Herramienta search

La herramienta search recibe la consulta de un usuario y devuelve una lista de resultados relevantes de la fuente de datos de tu servidor MCP.

Argumentos:

Una sola cadena de texto con la consulta.

Devuelve:

Un objeto con una sola clave, results, cuyo valor es un arreglo de objetos de resultado. Cada objeto debe incluir lo siguiente:

• id: ID único del documento o elemento encontrado.
• title: título legible para las personas.
• url: URL canónica para citar el resultado.

En MCP, devuelve este objeto como structuredContent e incluye el mismo valor como una cadena codificada en JSON en el arreglo de contenido para mantener la compatibilidad.

La respuesta final de la herramienta debe tener esta estructura:

1234567891011{
  "structuredContent": {
    "results": [{ "id": "doc-1", "title": "...", "url": "..." }]
  },
  "content": [
    {
      "type": "text",
      "text": "{\"results\":[{\"id\":\"doc-1\",\"title\":\"...\",\"url\":\"...\"}]}"
    }
  ]
}

Herramienta fetch

La herramienta fetch permite recuperar el contenido completo de un documento o elemento encontrado en una búsqueda.

Argumentos:

Una cadena de texto con el identificador único del documento encontrado.

Devuelve:

Un solo objeto con las siguientes propiedades:

• id: ID único del documento o elemento encontrado.
• title: cadena de texto con el título del elemento encontrado.
• text: texto completo del documento o elemento.
• url: URL del documento o elemento encontrado. Sirve para citar recursos específicos en una investigación.
• metadata: pares opcionales de clave y valor con datos sobre el resultado.

En MCP, devuelve este objeto como structuredContent e incluye el mismo valor como una cadena codificada en JSON en el arreglo de contenido para mantener la compatibilidad.

La respuesta final de la herramienta debe tener esta estructura:

123456789101112131415{
  "structuredContent": {
    "id": "doc-1",
    "title": "...",
    "text": "full text...",
    "url": "https://example.com/doc",
    "metadata": { "source": "vector_store" }
  },
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"doc-1\",\"title\":\"...\",\"text\":\"full text...\",\"url\":\"https://example.com/doc\",\"metadata\":{\"source\":\"vector_store\"}}"
    }
  ]
}

Cómo se generan las citas

Tanto para los resultados de search como para las respuestas de fetch, ChatGPT solo crea metadatos de cita cuando url es una cadena no vacía. Si un resultado tiene title pero carece de una url utilizable, ChatGPT lo conserva como una salida normal de la herramienta sin generar una cita vacía. Para que se pueda citar un resultado, devuelve su url canónica.

Por ejemplo, ChatGPT podría llamar a search con esta consulta:

{ "query": "What is the quarterly plan?" }

El servidor MCP puede devolver un resultado con una URL:

1234567891011121314151617{
  "structuredContent": {
    "results": [
      {
        "id": "quarterly-plan",
        "title": "Quarterly plan",
        "url": "https://example.com/quarterly-plan"
      }
    ]
  },
  "content": [
    {
      "type": "text",
      "text": "{\"results\":[{\"id\":\"quarterly-plan\",\"title\":\"Quarterly plan\",\"url\":\"https://example.com/quarterly-plan\"}]}"
    }
  ]
}

En esta respuesta, el campo url tiene un valor que permite generar metadatos de cita para el resultado. La consulta por sí sola no activa el procesamiento de citas. Si el resultado omite url o proporciona un valor vacío o de un tipo distinto de cadena, ChatGPT conserva el resultado como una salida normal de la herramienta.

Ejemplo de servidor

Puedes probar este servidor MCP de ejemplo en un entorno de desarrollo en el navegador. Configura el ejemplo con tus propias credenciales de la API y los datos de tu almacén de vectores.

Aquí también puedes consultar la implementación completa de las herramientas search y fetch en FastMCP.

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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211# Replace the illustrative IDs and URLs below with your own resource values.
"""
Sample MCP Server for ChatGPT Integration

This server implements the Model Context Protocol (MCP) with search and fetch
capabilities designed to work with ChatGPT's chat and deep research features.
"""

import logging
import os
from typing import Any

from fastmcp import FastMCP
from openai import OpenAI
from pydantic import BaseModel


class SearchResult(BaseModel):
    id: str
    title: str
    url: str


class SearchOutput(BaseModel):
    results: list[SearchResult]


class FetchOutput(BaseModel):
    id: str
    title: str
    text: str
    url: str
    metadata: dict[str, Any] | None = None


# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# OpenAI configuration
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
VECTOR_STORE_ID = "vs_123"

# Initialize OpenAI client
openai_client = OpenAI(api_key=OPENAI_API_KEY)

server_instructions = """
This MCP server provides search and document retrieval capabilities
for ChatGPT Apps and deep research. Use the search tool to find relevant documents
based on keywords, then use the fetch tool to retrieve complete
document content with citations.
"""


def create_server():
    """Create and configure the MCP server with search and fetch tools."""

    # Initialize the FastMCP server
    mcp = FastMCP(name="Sample MCP Server", instructions=server_instructions)

    @mcp.tool(output_schema=SearchOutput.model_json_schema())
    async def search(query: str) -> SearchOutput:
        """
        Search for documents using OpenAI Vector Store search.

        This tool searches through the vector store to find semantically relevant matches.
        Returns a list of search results with basic information. Use the fetch tool to get
        complete document content.

        Args:
            query: Search query string. Natural language queries work best for semantic search.

        Returns:
            Dictionary with 'results' key containing list of matching documents.
            Each result includes id, title, and URL.
        """
        if not query or not query.strip():
            return SearchOutput(results=[])

        if not openai_client:
            logger.error("OpenAI client not initialized - API key missing")
            raise ValueError("OpenAI API key is required for vector store search")

        # Search the vector store using OpenAI API
        logger.info(f"Searching {VECTOR_STORE_ID} for query: '{query}'")

        response = openai_client.vector_stores.search(
            vector_store_id=VECTOR_STORE_ID, query=query
        )

        results = []

        # Process the vector store search results
        if hasattr(response, "data") and response.data:
            for i, item in enumerate(response.data):
                # Extract file_id, filename, and content
                item_id = getattr(item, "file_id", f"vs_{i}")
                item_filename = getattr(item, "filename", f"Document {i + 1}")

                result = SearchResult(
                    id=item_id,
                    title=item_filename,
                    url=f"https://platform.openai.com/storage/files/{item_id}",
                )

                results.append(result)

        logger.info(f"Vector store search returned {len(results)} results")
        return SearchOutput(results=results)

    @mcp.tool(output_schema=FetchOutput.model_json_schema())
    async def fetch(id: str) -> FetchOutput:
        """
        Retrieve complete document content by ID for detailed
        analysis and citation. This tool fetches the full document
        content from OpenAI Vector Store. Use this after finding
        relevant documents with the search tool to get complete
        information for analysis and proper citation.

        Args:
            id: File ID from vector store (file-xxx) or local document ID

        Returns:
            Complete document with id, title, full text content,
            optional URL, and metadata

        Raises:
            ValueError: If the specified ID is not found
        """
        if not id:
            raise ValueError("Document ID is required")

        if not openai_client:
            logger.error("OpenAI client not initialized - API key missing")
            raise ValueError(
                "OpenAI API key is required for vector store file retrieval"
            )

        logger.info(f"Fetching content from vector store for file ID: {id}")

        # Fetch file content from vector store
        content_response = openai_client.vector_stores.files.content(
            vector_store_id=VECTOR_STORE_ID, file_id=id
        )

        # Get file metadata
        file_info = openai_client.vector_stores.files.retrieve(
            vector_store_id=VECTOR_STORE_ID, file_id=id
        )

        # Extract content from paginated response
        file_content = ""
        if hasattr(content_response, "data") and content_response.data:
            # Combine all content chunks from FileContentResponse objects
            content_parts = []
            for content_item in content_response.data:
                if hasattr(content_item, "text"):
                    content_parts.append(content_item.text)
            file_content = "\n".join(content_parts)
        else:
            file_content = "No content available"

        # Use filename as title and create proper URL for citations
        filename = openai_client.files.retrieve(file_id=id).filename

        result = FetchOutput(
            id=id,
            title=filename,
            text=file_content,
            url=f"https://platform.openai.com/storage/files/{id}",
        )

        # Add metadata if available from file info
        if hasattr(file_info, "attributes") and file_info.attributes:
            result.metadata = dict(file_info.attributes)

        logger.info(f"Fetched vector store file: {id}")
        return result

    return mcp


def main():
    """Main function to start the MCP server."""
    logger.info(f"Using vector store: {VECTOR_STORE_ID}")

    # Create the MCP server
    server = create_server()

    # Configure and start the server
    logger.info("Starting MCP server on 0.0.0.0:8000")
    logger.info("Server will be accessible via SSE transport")

    try:
        # Use FastMCP's built-in run method with SSE transport
        port = int(os.environ.get("OPENAI_EXAMPLE_PORT", "8000"))
        server.run(
            transport="sse",
            host="0.0.0.0",
            port=port,
            uvicorn_config={"loop": "asyncio"},
        )
    except KeyboardInterrupt:
        logger.info("Server stopped by user")
    except Exception as e:
        logger.error(f"Server error: {e}")
        raise


if __name__ == "__main__":
    main()

https://777xxx.janeway.replit.dev/sse/

Prueba y conecta tu servidor MCP

Puedes probar tu servidor MCP con gpt-6.1-sol en el panel de prompts. Crea un prompt o edita uno existente y agrega una herramienta MCP a la configuración del prompt. Este ejemplo de compatibilidad solo expone las herramientas de solo lectura search y fetch, por lo que la solicitud a la API omite la aprobación para esas herramientas. Mantén activada la aprobación para las herramientas que puedan modificar datos o realizar otras acciones con consecuencias importantes.

Si estás probando este servidor como parte de un complemento, sigue las instrucciones de Conecta y prueba tu complemento.

Una vez que hayas configurado tu servidor MCP, podrás conversar desde la interfaz de prompts con un modelo que use el servidor.

Puedes probar el servidor MCP directamente con la Responses API mediante una solicitud como esta:

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
41curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "You are a research assistant that searches MCP servers to find answers to your questions."
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Are cats attached to their homes? Give a succinct one page overview."
        }
      ]
    }
  ],
  "reasoning": {
    "summary": "auto"
  },
  "tools": [
    {
      "type": "mcp",
      "server_label": "cats",
      "server_url": "https://777ff573-9947-4b9c-8982-658fa40c7d09-00-3le96u7wsymx.janeway.replit.dev/sse/",
      "allowed_tools": [
        "search",
        "fetch"
      ],
      "require_approval": "never"
    }
  ]
}'

Gestiona la autenticación

Al crear un servidor MCP remoto personalizado, puedes proteger tus datos mediante la autorización y la autenticación. Para registrar clientes, recomendamos usar OAuth con documentos de metadatos de ID de cliente cuando tu servidor de autorización admita CIMD y quien cree el complemento elija esa opción. ChatGPT admite CIMD con intercambio de tokens para clientes públicos (none) o con intercambio de tokens mediante una aserción firmada del cliente (private_key_jwt). El registro dinámico de clientes sigue disponible si se configura. Para conocer los requisitos de autenticación de los complementos, consulta Autenticación. Para obtener detalles del protocolo, consulta la guía de usuario de MCP o la especificación de autorización.

Si conectas tu servidor MCP remoto personalizado mediante un complemento, los usuarios de tu Espacio de trabajo accederán a tu servicio mediante un flujo de OAuth.

Conecta el servidor en ChatGPT

1. Ve a Complementos de ChatGPT, selecciona el botón con el signo más y luego Agregar servidor MCP personalizado.
2. Ingresa la URL del servidor y los datos de autenticación. Lee la advertencia sobre los riesgos y selecciona Entiendo y quiero continuar y luego Crear como complemento.
3. Instala tu complemento y pruébalo con prompts en el chat y en la investigación profunda.

Para ver los pasos de configuración en detalle, consulta Conecta y prueba tu complemento.

Riesgos y seguridad

Los servidores MCP personalizados te permiten conectar tu Espacio de trabajo de ChatGPT con aplicaciones externas para que ChatGPT pueda acceder a los datos de esas aplicaciones, enviarlos y recibirlos. Ten en cuenta que OpenAI no desarrolla ni verifica los servidores MCP personalizados. Son servicios de terceros sujetos a sus propios términos y condiciones.

Si encuentras un servidor MCP malicioso, repórtalo a security@openai.com.

Riesgos relacionados con la inyección de prompts

La inyección de prompts es un tipo de ataque en el que alguien inserta instrucciones maliciosas en contenido que probablemente encuentre uno de nuestros modelos, como una página web, para que esas instrucciones alteren el comportamiento previsto de ChatGPT. Si el modelo obedece las instrucciones inyectadas, puede realizar acciones que ni el usuario ni el desarrollador tenían previstas, como enviar datos privados a un destino externo.

Por ejemplo, podrías pedirle a ChatGPT que consulte tu calendario y tus correos recientes para buscar un restaurante para una cena en grupo. Durante la búsqueda, podría encontrar un comentario malicioso diseñado para engañar al agente y hacer que realice acciones imprevistas. El comentario podría indicarle que obtenga de Gmail un código de restablecimiento de contraseña y lo envíe a un sitio web malicioso.

La siguiente tabla describe situaciones concretas que conviene tener en cuenta. Te recomendamos revisarla con atención antes de decidir si vas a usar servidores MCP personalizados.

Riesgos ajenos a la inyección de prompts

Los servidores MCP personalizados presentan otros riesgos que no dependen de los ataques de inyección de prompts:

• Las acciones de escritura pueden aumentar tanto la utilidad como los riesgos de los servidores MCP, ya que permiten que el servidor realice acciones potencialmente destructivas, además de proporcionar información a ChatGPT. Actualmente, ChatGPT exige una confirmación manual en cualquier conversación antes de realizar acciones de escritura. La confirmación señalará los datos potencialmente sensibles. Usa acciones de escritura solo si has evaluado con atención la posibilidad de que ChatGPT cometa un error al realizarlas y estás dispuesto a asumir ese riesgo. Pueden producirse acciones de escritura incluso si el servidor MCP las ha marcado como de solo lectura. Por eso es aún más importante que confíes en el servidor MCP personalizado antes de implementarlo en ChatGPT.
• Cualquier servidor MCP puede recibir datos sensibles en las consultas. Incluso si el servidor no es malicioso, tendrá acceso a todos los datos que ChatGPT le proporcione durante la interacción. Estos podrían incluir datos sensibles que el usuario haya compartido antes con ChatGPT. Por ejemplo, estos datos podrían aparecer en las consultas que ChatGPT envía al servidor MCP cuando usa la investigación profunda o las herramientas de aplicaciones en el chat.

Conexión con servidores de confianza

Te recomendamos conectarte a un servidor MCP personalizado solo si conoces la aplicación subyacente y confías en ella.

Por ejemplo, elige servidores oficiales alojados por los propios proveedores del servicio. Conéctate al servidor que Stripe aloja en mcp.stripe.com en lugar de usar un servidor MCP no oficial de Stripe alojado por un tercero. Como hoy hay pocos servidores MCP oficiales disponibles, podrías considerar uno alojado por una organización que reenvíe las solicitudes a otro servicio mediante una API. Conéctate solo después de revisar cómo usa la organización tus datos y verificar que puedes confiar en el servidor. Cuando crees tu propio servidor MCP y te conectes a él, vuelve a comprobar que sea el servidor correcto. Cuando OpenAI llame a tu servidor MCP, ten cuidado con los datos que proporcionas en respuesta a las solicitudes y con el tratamiento que das a los datos que recibes.

Tu servidor MCP remoto permite que otras personas conecten OpenAI con tus servicios. También permite que OpenAI acceda a los datos de esos servicios, envíe y reciba datos, y realice acciones en ellos. Evita incluir información sensible en el JSON de tus herramientas y almacenar información sensible de los usuarios de ChatGPT que accedan a tu servidor MCP remoto.

Al crear un servidor MCP, evita incluir contenido malicioso en las definiciones de tus herramientas.