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 los modelos de IA con herramientas y conocimientos adicionales. Los servidores MCP remotos permiten conectar modelos por Internet con nuevas fuentes de datos y capacidades.

En esta guía, veremos cómo crear un servidor MCP remoto que lee datos de una fuente privada (un almacén de vectores) y los pone a disposición mediante un complemento en ChatGPT y Codex, mediante la investigación profunda y el conocimiento de la empresa de ChatGPT, y a través de la API.

Nota: para crear un complemento con un servidor MCP, comienza con la documentación de 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 de usuario.

Configurar una fuente de datos

Puedes usar datos de cualquier fuente para alimentar un servidor MCP remoto, pero, para simplificar, usaremos almacenes de vectores de la API de OpenAI. Comienza por subir un documento PDF a un nuevo almacén de vectores; como ejemplo, puedes usar este libro sobre gatos del siglo XIX que es de dominio público.

Puedes subir archivos y crear un almacén de vectores aquí, en el panel, o hacerlo mediante la API. Sigue la guía de almacenes de vectores para configurar uno y subirle un archivo.

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

Crear un servidor MCP

Ahora, crearemos un servidor MCP remoto que realice búsquedas en nuestro almacén de vectores y pueda devolver el contenido de los documentos correspondientes a archivos con un ID determinado.

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

Ten en cuenta que existen otros frameworks para servidores MCP que puedes usar en distintos lenguajes de programación. Sin embargo, independientemente del framework que uses, las definiciones de herramientas de tu servidor deberán ajustarse a la estructura que se describe aquí.

Para funcionar con la investigación profunda y el conocimiento de la empresa de ChatGPT, tu servidor MCP debe implementar dos herramientas de solo lectura: search y fetch, usando el esquema de compatibilidad de Compatibilidad con el conocimiento de la empresa. La misma interfaz es útil para flujos de trabajo de investigación mediante la API.

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

Herramienta search

La herramienta search se encarga de devolver una lista de resultados de búsqueda relevantes de la fuente de datos de tu servidor MCP, a partir de la consulta de un usuario.

Argumentos:

Una sola cadena de consulta.

Devuelve:

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

• id - un ID único para el documento o elemento del resultado de búsqueda
• title - un título legible para las personas.
• url - una URL canónica para las citas.

En MCP, devuelve este objeto como structuredContent e incluye el mismo valor como una cadena codificada en JSON en el arreglo content 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 se usa para recuperar el contenido completo de un documento o elemento de los resultados de búsqueda.

Argumentos:

Una cadena que identifica de forma única el documento de la búsqueda.

Devuelve:

Un solo objeto con las siguientes propiedades:

• id - un ID único para el documento o elemento del resultado de búsqueda
• title - un título de tipo cadena para el elemento del resultado de búsqueda
• text - el texto completo del documento o elemento
• url - una URL del documento o elemento del resultado de búsqueda. Es útil para citar recursos específicos en una investigación.
• metadata - datos opcionales sobre el resultado en pares clave/valor

En MCP, devuelve este objeto como structuredContent e incluye el mismo valor como una cadena codificada en JSON en el arreglo content 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\"}}"
    }
  ]
}

Funcionamiento de las citas

Tanto para los resultados de search como para las respuestas de fetch, ChatGPT crea metadatos de citas solo cuando url es una cadena no vacía. Un resultado con un title pero sin una url utilizable sigue siendo una salida normal de la herramienta en lugar de convertirse en una cita vacía. Para que un resultado se pueda citar, devuelve su url canónica.

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

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

El servidor MCP puede responder con un resultado que incluya 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, lo que permite que se generen metadatos de citas 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 basado en el navegador. Configura el ejemplo con tus propias credenciales de API y la información de tu almacén de vectores.

Para facilitar la consulta, a continuación también se incluye una 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 = getattr(file_info, "filename", f"Document {id}")

        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/

Probar y conectar tu servidor MCP

Puedes probar tu servidor MCP con un modelo de investigación profunda en el panel de prompts. Crea un prompt nuevo o edita uno existente y agrega una nueva 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 su solicitud a la API omite la aprobación para esas herramientas. Mantén habilitada 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 Conecta y prueba tu complemento.

Una vez que hayas configurado tu servidor MCP, puedes conversar con un modelo que lo use desde la interfaz de Prompts.

Puedes probar el servidor MCP directamente con la API Responses 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-5.6-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"
    }
  ]
}'

Gestionar la autenticación

Al crear un servidor MCP remoto personalizado, la autorización y la autenticación te ayudan a proteger tus datos. Recomendamos usar OAuth con documentos de metadatos de ID de cliente para registrar clientes cuando tu servidor de autorización sea compatible con CIMD y quien cree el complemento elija esta opción. ChatGPT admite CIMD con intercambio de tokens para clientes públicos (none) o intercambio de tokens mediante una aserción de cliente firmada (private_key_jwt). El registro dinámico de clientes sigue siendo compatible cuando está configurado. Para conocer los requisitos de autenticación de los complementos, consulta Autenticación. Para conocer los detalles del protocolo, lee la guía del 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 tendrán un flujo de OAuth para conectarse a tu servicio.

Conectar en ChatGPT

1. En ChatGPT, abre Configuración → Seguridad e inicio de sesión y activa el Modo de desarrollador.
2. Ve a Complementos de ChatGPT, selecciona el botón con el signo más y conecta la URL de tu servidor en modo de desarrollador.
3. Prueba tu complemento ejecutando prompts en el chat y en investigación profunda.

Para ver los pasos de configuración detallados, consulta Conectar y probar tu complemento.

Riesgos y seguridad

Los servidores MCP personalizados te permiten conectar tu espacio de trabajo de ChatGPT con aplicaciones externas, lo que permite a ChatGPT acceder a los datos de estas 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 un atacante incorpora instrucciones maliciosas en contenido que alguno de nuestros modelos probablemente encuentre, como una página web, con la intención de que esas instrucciones anulen el comportamiento previsto de ChatGPT. Si el modelo obedece las instrucciones inyectadas, puede realizar acciones que el usuario y el desarrollador nunca pretendieron, incluido el envío de datos privados a un destino externo.

Por ejemplo, podrías pedirle a ChatGPT que encuentre un restaurante para una cena en grupo consultando tu calendario y tus correos recientes. Durante la investigación, podría encontrar un comentario malicioso, es decir, contenido dañino diseñado para engañar al agente y hacer que realice acciones no deseadas, que le indique obtener un código de restablecimiento de contraseña de Gmail y enviarlo a un sitio web malicioso.

A continuación se presenta una tabla con situaciones específicas que debes considerar. Recomendamos revisarla con atención para tomar una decisión informada sobre el uso de MCP personalizados.

Riesgos no relacionados con la inyección de prompts

Los MCP personalizados introducen otros riesgos que no están relacionados con los ataques de inyección de prompts:

• Las acciones de escritura pueden aumentar tanto la utilidad como los riesgos de los servidores MCP, porque permiten que el servidor realice acciones potencialmente destructivas en lugar de limitarse a devolver información a ChatGPT. Actualmente, ChatGPT requiere una confirmación manual en cualquier conversación antes de realizar acciones de escritura. La confirmación señalará los datos potencialmente sensibles, pero solo debes usar acciones de escritura en situaciones en las que hayas considerado cuidadosamente y estés dispuesto a aceptar la posibilidad de que ChatGPT cometa un error al realizarlas. Es posible que se realicen acciones de escritura incluso si el servidor MCP las ha etiquetado como de solo lectura, por lo que 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 como parte de las consultas. Incluso si el servidor no es malicioso, tendrá acceso a todos los datos que ChatGPT proporcione durante la interacción, lo que podría incluir datos sensibles que el usuario haya compartido antes con ChatGPT. Por ejemplo, esos datos podrían incluirse en las consultas que ChatGPT envíe al servidor MCP al usar investigación profunda o herramientas de apps en el chat.

Conectarse a servidores de confianza

Recomendamos que no te conectes a un servidor MCP personalizado a menos que conozcas la aplicación subyacente y confíes en ella.

Por ejemplo, elige servidores oficiales alojados por los propios proveedores de servicios. Conéctate al servidor de Stripe alojado por Stripe en mcp.stripe.com, en lugar de usar un servidor MCP de Stripe no oficial alojado por un tercero. Como actualmente hay pocos servidores MCP oficiales disponibles, podrías considerar un servidor alojado por una organización que reenvíe solicitudes a otro servicio mediante una API. Conéctate solo después de revisar cómo usa tus datos la organización y verificar que puedes confiar en el servidor. Al crear tu propio servidor MCP y conectarte a él, comprueba que sea el servidor correcto. Ten cuidado con los datos que proporcionas en respuesta a las solicitudes y con la forma en que tratas los datos que recibes cuando OpenAI llama a tu servidor MCP.

Tu servidor MCP remoto permite que otros conecten OpenAI con tus servicios y que OpenAI acceda a los datos, los envíe y los reciba, y realice acciones en esos servicios. 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, no incluyas contenido malicioso en las definiciones de tus herramientas.