GPT-5 MCP Server

Instructions

Implementation Reference

• src/index.ts:39-59 (registration)

  Registers the gpt5_query tool on the MCP server with input schema and handler function that delegates to runQuery in openai.ts.

  server.tool(
    "gpt5_query",
    "Query GPT-5 with optional Web Search Preview. Supports verbosity and reasoning effort.",
    { input: QueryInputSchema },
    async ({ input }) => {
      const parsed = QueryInputSchema.parse(input);
      try {
        const text = await runQuery(openai, parsed as QueryInput, config);
        return {
          content: [{ type: "text" as const, text: text || "No response text available." }],
        };
      } catch (error) {
        console.error("Error calling OpenAI API:", error);
        const message = error instanceof Error ? error.message : "Unknown error";
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/index.ts:21-37 (schema)

  Zod input schema for the gpt5_query tool defining all parameters like query, model overrides, web_search options etc.

  const QueryInputSchema = z.object({
    query: z.string().describe("User question or instruction"),
    // Per-call overrides
    model: z.string().optional().describe("Model name, e.g. gpt-5"),
    system: z.string().optional().describe("Optional system prompt/instructions for the model"),
    reasoning_effort: z.enum(["low", "minimal", "medium", "high"]).optional(),
    verbosity: z.enum(["low", "medium", "high"]).optional(),
    tool_choice: z.enum(["auto", "none"]).optional(),
    parallel_tool_calls: z.boolean().optional(),
    max_output_tokens: z.number().int().positive().optional(),
    web_search: z
      .object({
        enabled: z.boolean().optional(),
        search_context_size: z.enum(["low", "medium", "high"]).optional(),
      })
      .optional(),
  });

• src/openai.ts:94-101 (handler)

  Core handler logic: builds OpenAI request and calls the API, extracts output text. Called directly by the registered tool handler.

  export async function runQuery(openai: OpenAI, input: QueryInput, cfg: AppConfig) {
    const req = buildOpenAIRequest(input, cfg);
    const response: unknown = await openai.responses.create(
      req as unknown as Record<string, unknown>
    );
    const text = extractOutputText(response) ?? "";
    return text || "No response text available.";
  }

• src/openai.ts:36-84 (helper)

  Helper function to build the structured OpenAI request from tool input and config, handling defaults, web search tool addition, reasoning adjustments etc.

  export function buildOpenAIRequest(input: QueryInput, cfg: AppConfig): OpenAIRequest {
    const model = input.model ?? cfg.model;
  
    const effRaw = (input.reasoning_effort ?? cfg.reasoningEffort) as
      | "low"
      | ReasoningEffort
      | undefined;
    let reasoningEffort: ReasoningEffort | undefined = effRaw
      ? ((effRaw === "low" ? "minimal" : effRaw) as ReasoningEffort)
      : undefined;
  
    // Bump reasoning for web search minimal constraint
    const webEnabled = input.web_search?.enabled ?? cfg.webSearchDefaultEnabled;
    if (reasoningEffort === "minimal" && webEnabled) {
      reasoningEffort = "medium";
    }
  
    const verbosity: Verbosity | undefined = input.verbosity ?? cfg.defaultVerbosity;
  
    const searchContextSize: SearchContextSize | undefined =
      input.web_search?.search_context_size ?? cfg.webSearchContextSize;
  
    const toolChoice = input.tool_choice ?? "auto";
    const parallelToolCalls = input.parallel_tool_calls ?? true;
  
    const tools: WebSearchPreviewTool[] = [];
    if (webEnabled) {
      const webTool: WebSearchPreviewTool = { type: "web_search_preview" };
      if (searchContextSize) {
        webTool.search_context_size = searchContextSize;
      }
      tools.push(webTool);
    }
  
    const req: OpenAIRequest = {
      model,
      input: input.query,
      tool_choice: toolChoice,
      parallel_tool_calls: parallelToolCalls,
    } as OpenAIRequest;
  
    if (input.system) req.instructions = input.system;
    if (tools.length > 0) req.tools = tools;
    if (reasoningEffort) req.reasoning = { effort: reasoningEffort };
    if (verbosity) req.text = { verbosity };
    if (input.max_output_tokens) req.max_output_tokens = input.max_output_tokens;
  
    return req;
  }

• src/openai.ts:4-17 (schema)

  TypeScript type matching the tool's input schema, used internally.

  export type QueryInput = {
    query: string;
    model?: string;
    system?: string;
    reasoning_effort?: "low" | "minimal" | "medium" | "high";
    verbosity?: Verbosity;
    tool_choice?: "auto" | "none";
    parallel_tool_calls?: boolean;
    max_output_tokens?: number;
    web_search?: {
      enabled?: boolean;
      search_context_size?: SearchContextSize;
    };
  };