Criação de servidores MCP para plug-ins e integrações de API

O Model Context Protocol (MCP) é um protocolo aberto que está se tornando o padrão do setor para ampliar as capacidades dos modelos de IA com ferramentas e conhecimentos adicionais. Servidores MCP remotos podem conectar modelos a novas fontes de dados e capacidades pela Internet.

Neste guia, veremos como criar um servidor MCP remoto que lê dados de uma fonte privada (um armazenamento vetorial) e os disponibiliza por meio de um plug-in no ChatGPT e no Codex, da pesquisa aprofundada e do conhecimento da empresa no ChatGPT e da API.

Observação: para criar um plug-in com um servidor MCP, comece pela documentação de plug-ins: Início rápido, Crie seu servidor MCP, Conecte e teste seu plug-in e Autenticação. Se o seu servidor MCP não precisar de uma interface de usuário, você poderá expor ferramentas sem recursos de interface.

Configure uma fonte de dados

Você pode usar dados de qualquer fonte em um servidor MCP remoto, mas, para simplificar, usaremos armazenamentos vetoriais na API da OpenAI. Comece enviando um documento PDF para um novo armazenamento vetorial. Como exemplo, você pode usar este livro do século XIX sobre gatos, que está em domínio público.

Você pode enviar arquivos e criar um armazenamento vetorial aqui no painel ou fazer isso pela API. Siga o guia de armazenamento vetorial para configurar um armazenamento vetorial e enviar um arquivo para ele.

Anote o ID exclusivo do armazenamento vetorial para usá-lo no exemplo a seguir.

Crie um servidor MCP

Agora, vamos criar um servidor MCP remoto que fará pesquisas no nosso armazenamento vetorial e poderá retornar o conteúdo dos documentos a partir de um ID de arquivo.

Neste exemplo, vamos criar nosso servidor MCP usando Python e FastMCP. Uma implementação completa do servidor está no final desta seção, junto com instruções para executá-lo em um ambiente de desenvolvimento no navegador.

Há vários outros frameworks de servidores MCP disponíveis para diversas linguagens de programação. Independentemente do framework escolhido, as definições das ferramentas no seu servidor precisarão seguir o formato descrito aqui.

Para funcionar com a pesquisa aprofundada e o conhecimento da empresa no ChatGPT, seu servidor MCP deve implementar duas ferramentas somente leitura: search e fetch, usando o esquema de compatibilidade descrito em Compatibilidade com o conhecimento da empresa. A mesma interface é útil para fluxos de trabalho de pesquisa via API.

Declare um esquema de saída para cada ferramenta para que os clientes possam validar o formato do resultado. No FastMCP, modelos de retorno tipados podem gerar esse esquema automaticamente; o exemplo abaixo passa output_schema explicitamente a partir dos mesmos modelos.

Ferramenta search

A ferramenta search é responsável por retornar uma lista de resultados de pesquisa relevantes da fonte de dados do seu servidor MCP, com base na consulta do usuário.

Argumentos:

Uma única string de consulta.

Retorno:

Um objeto com uma única chave, results, cujo valor é um array de objetos de resultado. Cada objeto de resultado deve incluir:

• id - um ID exclusivo para o documento ou item do resultado da pesquisa
• title - título legível por pessoas.
• url - URL canônica para citação.

No MCP, retorne esse objeto como structuredContent e inclua o mesmo valor como uma string codificada em JSON no array content para manter a compatibilidade.

A resposta final da ferramenta deve ter este formato:

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

Ferramenta fetch

A ferramenta fetch é usada para recuperar o conteúdo completo de um documento ou item retornado na pesquisa.

Argumentos:

Uma string que identifica de forma exclusiva o documento da pesquisa.

Retorno:

Um único objeto com as seguintes propriedades:

• id - um ID exclusivo para o documento ou item do resultado da pesquisa
• title - um título em formato de string para o item do resultado da pesquisa
• text - O texto completo do documento ou item
• url - uma URL para o documento ou item do resultado da pesquisa. Útil para citar recursos específicos em pesquisas.
• metadata - dados opcionais sobre o resultado em pares de chave/valor

No MCP, retorne esse objeto como structuredContent e inclua o mesmo valor como uma string codificada em JSON no array content para manter a compatibilidade.

A resposta final da ferramenta deve ter este formato:

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\"}}"
    }
  ]
}

Comportamento das citações

Tanto nos resultados de search quanto nas respostas de fetch, o ChatGPT cria metadados de citação somente quando url é uma string não vazia. Um resultado com title, mas sem um url utilizável, continua sendo uma saída comum da ferramenta, em vez de se tornar uma citação vazia. Para que um resultado possa ser citado, retorne seu url canônico.

Por exemplo, o ChatGPT pode chamar search com:

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

O servidor MCP pode responder com um resultado associado a uma 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\"}]}"
    }
  ]
}

Nesta resposta, o campo url tem um valor, o que permite que o resultado receba metadados de citação. A consulta em si não aciona o tratamento de citações. Se o resultado omitir url ou fornecer um valor vazio ou que não seja uma string, o ChatGPT preservará o resultado como uma saída comum da ferramenta.

Exemplo de servidor

Você pode experimentar este servidor MCP de exemplo em um ambiente de desenvolvimento no navegador. Configure o exemplo com suas próprias credenciais de API e informações do armazenamento vetorial.

Para sua conveniência, uma implementação completa das ferramentas search e fetch no FastMCP também está disponível abaixo.

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/

Teste e conecte seu servidor MCP

Você pode testar seu servidor MCP com um modelo de pesquisa aprofundada no painel de prompts. Crie um novo prompt ou edite um existente e adicione uma nova ferramenta MCP à configuração do prompt. Este exemplo de compatibilidade expõe apenas as ferramentas somente leitura search e fetch, por isso a requisição à API dispensa a aprovação dessas ferramentas. Mantenha a aprovação ativada para ferramentas que possam modificar dados ou realizar outras ações com consequências relevantes.

Se você estiver testando este servidor como parte de um plug-in, siga as instruções em Conecte e teste seu plug-in.

Depois de configurar seu servidor MCP, você pode conversar com um modelo que o utilize pela interface de Prompts.

Você pode testar o servidor MCP diretamente com a Responses API usando uma requisição 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"
    }
  ]
}'

Configurar a autenticação

Ao criar um servidor MCP remoto personalizado, a autorização e a autenticação ajudam você a proteger seus dados. Recomendamos usar OAuth com Client ID Metadata Documents para o registro de clientes quando seu servidor de autorização oferecer suporte a CIMD e o criador do plug-in optar por esse recurso. O ChatGPT oferece suporte a CIMD com troca de tokens para clientes públicos (none) ou troca de tokens com asserção de cliente assinada (private_key_jwt). O registro dinâmico de clientes continua disponível quando configurado. Para conhecer os requisitos de autenticação de plug-ins, consulte Autenticação. Para saber mais sobre o protocolo, leia o guia do usuário do MCP ou a especificação de autorização.

Se você conectar seu servidor MCP remoto personalizado por meio de um plug-in, os usuários do seu workspace passarão por um fluxo OAuth para acessar seu serviço.

Conectar no ChatGPT

1. No ChatGPT, abra Configurações → Segurança e login e ative o Modo de desenvolvedor.
2. Acesse Plug-ins do ChatGPT, selecione o botão de adição e conecte a URL do seu servidor no modo de desenvolvedor.
3. Teste seu plug-in executando prompts no chat e na pesquisa aprofundada.

Para ver as etapas detalhadas de configuração, consulte Conectar e testar seu plug-in.

Riscos e segurança

Servidores MCP personalizados permitem conectar seu workspace do ChatGPT a aplicativos externos, possibilitando que o ChatGPT acesse, envie e receba dados nesses aplicativos. Os servidores MCP personalizados não são desenvolvidos nem verificados pela OpenAI. São serviços de terceiros sujeitos aos próprios termos e condições.

Se você encontrar um servidor MCP malicioso, denuncie-o para security@openai.com.

Riscos relacionados à injeção de prompt

A injeção de prompt é um tipo de ataque em que um invasor insere instruções maliciosas em um conteúdo que um de nossos modelos provavelmente encontrará, como uma página da Web, com o objetivo de substituir o comportamento esperado do ChatGPT. Se o modelo obedecer às instruções injetadas, poderá realizar ações que o usuário e o desenvolvedor nunca pretenderam, incluindo o envio de dados privados a um destino externo.

Por exemplo, você pode pedir ao ChatGPT que encontre um restaurante para um jantar em grupo consultando seu calendário e seus e-mails recentes. Durante a pesquisa, ele pode encontrar um comentário malicioso, ou seja, um conteúdo nocivo criado para enganar o agente e induzi-lo a realizar ações indesejadas, instruindo-o a buscar um código de redefinição de senha no Gmail e enviá-lo a um site malicioso.

A tabela abaixo apresenta cenários específicos a considerar. Recomendamos analisá-la com atenção para decidir se você deve usar servidores MCP personalizados.

Riscos não relacionados à injeção de prompt

Servidores MCP personalizados introduzem outros riscos não relacionados a ataques de injeção de prompt:

• As ações de escrita podem aumentar tanto a utilidade quanto os riscos dos servidores MCP, pois permitem que o servidor realize ações potencialmente destrutivas, em vez de apenas fornecer informações ao ChatGPT. Atualmente, o ChatGPT exige confirmação manual em qualquer conversa antes que ações de escrita possam ser realizadas. A confirmação sinaliza dados potencialmente sensíveis, mas você só deve usar ações de escrita em situações nas quais tenha avaliado cuidadosamente e aceite a possibilidade de o ChatGPT cometer um erro envolvendo esse tipo de ação. Ações de escrita podem ocorrer mesmo que o servidor MCP tenha classificado a ação como somente leitura, o que torna ainda mais importante confiar no servidor MCP personalizado antes de disponibilizá-lo no ChatGPT.
• Qualquer servidor MCP pode receber dados sensíveis como parte de uma consulta. Mesmo que o servidor não seja malicioso, ele terá acesso a todos os dados que o ChatGPT fornecer durante a interação, o que pode incluir dados sensíveis que o usuário tenha fornecido anteriormente ao ChatGPT. Por exemplo, esses dados podem ser incluídos nas consultas que o ChatGPT envia ao servidor MCP ao usar a pesquisa aprofundada ou ferramentas de aplicativos no chat.

Conectar-se a servidores confiáveis

Recomendamos que você só se conecte a um servidor MCP personalizado se conhecer e confiar no aplicativo ao qual ele dá acesso.

Por exemplo, escolha servidores oficiais hospedados pelos próprios provedores de serviços. Conecte-se ao servidor da Stripe hospedado pela Stripe em mcp.stripe.com, em vez de usar um servidor MCP não oficial da Stripe hospedado por terceiros. Como hoje há poucos servidores MCP oficiais disponíveis, você pode considerar um servidor hospedado por uma organização que encaminha requisições a outro serviço por meio de uma API. Só se conecte depois de analisar como a organização usa seus dados e verificar se o servidor é confiável. Ao criar seu próprio servidor MCP e se conectar a ele, confira se é o servidor correto. Tenha cuidado com os dados que você fornece em resposta às solicitações e com a forma como trata os dados enviados a você quando a OpenAI chama seu servidor MCP.

Seu servidor MCP remoto permite que outras pessoas conectem a OpenAI aos seus serviços e que a OpenAI acesse, envie e receba dados, além de realizar ações nesses serviços. Evite incluir informações sensíveis no JSON das suas ferramentas e armazenar informações sensíveis de usuários do ChatGPT que acessam seu servidor MCP remoto.

Ao criar um servidor MCP, não inclua nada malicioso nas definições das suas ferramentas.