Como criar servidores MCP para plugins e integrações de API

O Model Context Protocol (MCP) é um protocolo aberto que vem se tornando o padrão do setor para ampliar os recursos dos modelos de IA com novas ferramentas e fontes de conhecimento. Com servidores MCP remotos, é possível conectar modelos pela internet a novas fontes de dados e funcionalidades.

Neste guia, você vai criar um servidor MCP remoto que lê dados de uma fonte privada (um armazenamento vetorial) e os disponibiliza por meio de um plugin no ChatGPT e no Codex, dos recursos de pesquisa aprofundada e conhecimento da empresa no ChatGPT e da API.

Observação: para criar um plugin com um servidor MCP, comece pela documentação de plugins: Início rápido, Crie seu servidor MCP, Conecte e teste seu plugin e Autenticação. Se o servidor MCP dispensar uma interface de usuário, você pode disponibilizar as ferramentas sem incluir recursos de interface.

Configure uma fonte de dados

Um servidor MCP remoto pode usar dados de qualquer fonte. Para simplificar, vamos usar armazenamentos vetoriais da 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 no painel. Também pode criar armazenamentos vetoriais e enviar arquivos pela API. Siga o guia de armazenamento vetorial para configurar um armazenamento e enviar um arquivo para ele.

Anote o ID exclusivo do armazenamento vetorial para usar no exemplo a seguir.

Crie um servidor MCP

Agora, crie um servidor MCP remoto que faça buscas no armazenamento vetorial e retorne o conteúdo de um documento a partir do ID do arquivo.

Neste exemplo, vamos criar o servidor MCP com Python e FastMCP. No final desta seção, você encontra a implementação completa do servidor e as instruções para executá-lo em um ambiente de desenvolvimento no navegador.

Há outros frameworks para criar servidores MCP em diversas linguagens de programação. Independentemente do framework escolhido, as definições das ferramentas do servidor precisam seguir o formato descrito aqui.

Para funcionar com os recursos de pesquisa aprofundada e conhecimento da empresa do ChatGPT, seu servidor MCP deve implementar duas ferramentas somente leitura, search e fetch, seguindo o schema descrito em Compatibilidade com o conhecimento da empresa. A mesma interface é útil para fluxos de pesquisa pela API.

Declare um schema de saída para cada ferramenta para que os clientes possam validar a estrutura do resultado. No FastMCP, modelos de retorno tipados podem gerar esse schema automaticamente. O exemplo abaixo usa os mesmos modelos para passar output_schema de forma explícita.

Ferramenta search

A ferramenta search recebe a consulta do usuário e retorna uma lista de resultados relevantes encontrados na fonte de dados do servidor MCP.

Argumentos:

Uma única string com a consulta.

Retorno:

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

• id - ID exclusivo do documento ou item encontrado na busca.
• title - título legível para o usuário.
• 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 de conteúdo para garantir 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 recupera o conteúdo completo de um documento ou item encontrado na busca.

Argumentos:

Uma string que identifica de forma exclusiva o documento encontrado.

Retorno:

Um único objeto com as seguintes propriedades:

• id - ID exclusivo do documento ou item encontrado na busca.
• title - string com o título do item encontrado.
• text - texto completo do documento ou item.
• url - URL do documento ou item encontrado. Serve para citar recursos específicos em uma pesquisa.
• metadata - dados opcionais sobre o resultado, organizados em pares de chave e valor.

No MCP, retorne esse objeto como structuredContent e inclua o mesmo valor como uma string codificada em JSON no array de conteúdo para garantir 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\"}}"
    }
  ]
}

Como funcionam as citações

Tanto nos resultados de search quanto nas respostas de fetch, o ChatGPT só cria metadados de citação quando url é uma string não vazia. Se um resultado tiver title, mas não tiver uma url utilizável, o ChatGPT o mantém como uma saída comum da ferramenta, sem criar uma citação vazia. Para que um resultado possa ser citado, retorne sua url canônica.

Por exemplo, o ChatGPT pode chamar search com a seguinte consulta:

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

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

Nessa resposta, o campo url está preenchido, o que permite associar metadados de citação ao resultado. A consulta por si só não aciona o processamento de citações. Se o resultado omitir url ou fornecer um valor vazio ou de um tipo diferente de string, o ChatGPT o mantém como uma saída comum da ferramenta.

Exemplo de servidor

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

Você também encontra abaixo a implementação completa das ferramentas search e fetch em 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/

Teste e conecte seu servidor MCP

Você pode testar seu servidor MCP com gpt-6.1-sol no painel de prompts. Crie um prompt ou edite um existente e adicione uma nova ferramenta MCP à configuração do prompt. Este exemplo de compatibilidade disponibiliza 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 alterar dados ou executar outras ações com consequências importantes.

Se você estiver testando esse servidor como parte de um plugin, siga as instruções em Conecte e teste seu plugin.

Depois de configurar o servidor MCP, você pode usar a interface de prompts para conversar com um modelo que tenha acesso ao servidor.

Para testar o servidor MCP diretamente pela Responses API, envie 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-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"
    }
  ]
}'

Configure a autenticação

Ao criar um servidor MCP remoto personalizado, use a autorização e a autenticação para proteger seus dados. Para registrar clientes, recomendamos usar OAuth com documentos de metadados de ID do cliente (CIMD) quando o servidor de autorização oferecer suporte a CIMD e o criador do plugin escolher essa opção. O ChatGPT oferece suporte a CIMD com troca de tokens para clientes públicos (none) ou troca de tokens com uma declaração assinada pelo cliente (private_key_jwt). O registro dinâmico de clientes continua disponível quando configurado. Para consultar os requisitos de autenticação dos plugins, veja 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 plugin, os usuários do seu espaço de trabalho passarão pelo fluxo OAuth do seu serviço.

Conecte o servidor no ChatGPT

1. Acesse Plug-ins do ChatGPT, selecione o botão com o sinal de mais e depois Adicionar servidor MCP personalizado.
2. Informe a URL do servidor e os detalhes de autenticação. Leia o aviso sobre os riscos e selecione Entendo e quero continuar. Em seguida, selecione Criar como plugin.
3. Instale o plugin e teste-o executando prompts no chat e na pesquisa aprofundada.

Para ver as etapas de configuração em detalhes, consulte Conecte e teste seu plugin.

Riscos e segurança

Com servidores MCP personalizados, você pode conectar seu espaço de trabalho do ChatGPT a aplicativos externos. Isso permite que o ChatGPT acesse, envie e receba dados nesses aplicativos. A OpenAI não desenvolve nem verifica servidores MCP personalizados. Esses serviços são de terceiros e estão sujeitos aos termos e condições dos respectivos provedores.

Se encontrar um servidor MCP malicioso, denuncie-o pelo e-mail security@openai.com.

Riscos relacionados à injeção de prompt

A injeção de prompt é um ataque em que alguém insere instruções maliciosas em conteúdo que um de nossos modelos provavelmente encontrará, como uma página da internet, para tentar alterar o comportamento previsto do ChatGPT. Se o modelo seguir essas instruções, poderá executar ações que nem o usuário nem o desenvolvedor pretendiam, inclusive enviar dados privados para um destino externo.

Por exemplo, você pode pedir ao ChatGPT que consulte seu calendário e seus e-mails recentes para encontrar um restaurante para um jantar em grupo. Durante a pesquisa, ele pode encontrar um comentário malicioso que o instrua a buscar um código de redefinição de senha no Gmail e enviá-lo a um site malicioso. O comentário é um conteúdo criado para induzir o agente a executar ações não solicitadas.

A tabela a seguir apresenta cenários específicos a considerar. Recomendamos que você os analise com atenção ao decidir se deve usar servidores MCP personalizados.

Outros riscos além da injeção de prompt

Servidores MCP personalizados também apresentam riscos que não dependem de ataques de injeção de prompt:

• As ações de gravação podem aumentar tanto a utilidade quanto os riscos dos servidores MCP, pois permitem que o servidor execute ações potencialmente destrutivas, além de fornecer informações ao ChatGPT. Atualmente, em qualquer conversa, o ChatGPT exige confirmação manual antes de executar ações de gravação. A solicitação de confirmação destaca dados potencialmente confidenciais. Use ações de gravação apenas depois de avaliar com cuidado a possibilidade de o ChatGPT cometer um erro ao executá-las e concluir que aceita esse risco. Uma ação de gravação pode ocorrer mesmo que o servidor MCP a tenha marcado como somente leitura. Por isso, é ainda mais importante verificar se você confia no servidor MCP personalizado antes de disponibilizá-lo no ChatGPT.
• Qualquer servidor MCP pode receber dados confidenciais em uma consulta. Mesmo que o servidor não seja malicioso, ele terá acesso a todos os dados que o ChatGPT enviar durante a interação. Isso pode incluir informações confidenciais que o usuário forneceu anteriormente ao ChatGPT. Esses dados podem aparecer, por exemplo, nas consultas que o ChatGPT envia ao servidor MCP ao usar a pesquisa aprofundada ou ferramentas de aplicativos de chat.

Conexão com servidores confiáveis

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

Por exemplo, escolha servidores oficiais hospedados pelos próprios provedores dos serviços. No caso da Stripe, conecte-se ao servidor hospedado pela própria Stripe em mcp.stripe.com em vez de usar um servidor MCP não oficial hospedado por terceiros. Como ainda existem poucos servidores MCP oficiais, você pode considerar usar um servidor hospedado por uma organização que encaminhe requisições a outro serviço por meio de uma API. Antes de se conectar, analise como a organização usa seus dados e verifique se o servidor é confiável. Ao criar seu próprio servidor MCP e se conectar a ele, confira se está usando o servidor correto. Tenha cuidado com os dados que você fornece em resposta a requisições e com a forma como trata os dados que recebe quando a OpenAI chama seu servidor MCP.

Seu servidor MCP remoto permite que outras pessoas conectem a OpenAI aos seus serviços. Assim, a OpenAI pode acessar, enviar e receber dados, além de executar ações nesses serviços. Evite incluir informações confidenciais no JSON das ferramentas ou armazenar informações confidenciais dos usuários do ChatGPT que acessam seu servidor MCP remoto.

Ao criar um servidor MCP, não inclua conteúdo malicioso nas definições das ferramentas.