GPT-5 MCP Server (TypeScript)

An MCP server that exposes a gpt5_query tool for GPT-5 inference via OpenAI Responses API, with optional Web Search Preview. Supports per-call overrides for verbosity, reasoning effort, and other parameters.

日本語

Features

• TypeScript MCP server using @modelcontextprotocol/sdk
• gpt5_query tool
  • web_search_preview integration (optional)
  • verbosity (low|medium|high)
  • reasoning.effort (low|medium|high)
  • tool_choice (auto|none), parallel_tool_calls
  • system prompt, model, max_output_tokens
• Config via environment variables with per-call overrides

Quick Start

1. Install dependencies

pnpm i # or npm i / yarn

1. Configure environment

Create .env (or export env vars):

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5
OPENAI_MAX_RETRIES=3
OPENAI_TIMEOUT_MS=60000
REASONING_EFFORT=medium
DEFAULT_VERBOSITY=medium
WEB_SEARCH_DEFAULT_ENABLED=false
WEB_SEARCH_CONTEXT_SIZE=medium

1. Build and run

pnpm run build
pnpm start

For development (watch mode):

pnpm run dev

Using with MCP Clients (Claude Code, Claude Desktop)

This server speaks Model Context Protocol (MCP) over stdio and emits pure JSON to stdout, making it safe for Claude Code and Claude Desktop.

Prerequisites

• Node.js 18+
• OpenAI API key via .env or environment variable

1. Build

pnpm run build

1. Run directly (recommended)

• Command: node
• Args: dist/cli.js
• CWD: repository root (required if you want .env to be loaded)

Example:

node dist/cli.js

1. Add to Claude Code (VS Code)

• Command Palette "Claude: Manage MCP Servers"
• "Add server" with:
  • Name: gpt5-mcp
  • Command: node (or absolute path, e.g., /opt/homebrew/bin/node)
  • Args: ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"] (or just gpt5-mcp-server if installed globally)
  • Env (choose one):
    • Option A (ENV_FILE): ENV_FILE=/absolute/path/to/gpt5-mcp-server/.env
    • Option B (explicit): set OPENAI_API_KEY, OPENAI_MODEL, OPENAI_TIMEOUT_MS, DEFAULT_VERBOSITY, REASONING_EFFORT, WEB_SEARCH_DEFAULT_ENABLED, WEB_SEARCH_CONTEXT_SIZE

1. Add to Claude Desktop
   Edit config (e.g., macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

Option A: using ENV_FILE

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "ENV_FILE": "/absolute/path/to/gpt5-mcp-server/.env"
      }
    }
  }
}

Option B: explicit env vars

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/gpt5-mcp-server/dist/cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-5",
        "OPENAI_TIMEOUT_MS": "120000",
        "DEFAULT_VERBOSITY": "medium",
        "REASONING_EFFORT": "low",
        "WEB_SEARCH_DEFAULT_ENABLED": "false",
        "WEB_SEARCH_CONTEXT_SIZE": "medium"
      }
    }
  }
}

1. CLI usage

• Package exposes bin(s).
  • Local link: npm link run gpt5-mcp-server
  • Global (after publish): npm i -g gpt5-mcp-server gpt5-mcp-server
  • Direct: node /absolute/path/to/gpt5-mcp-server/dist/cli.js

1. Web Search notes

• Due to OpenAI constraints, web_search_preview cannot be combined with reasoning.effort = minimal.
• This server automatically bumps effort to medium if web_search.enabled = true.
• If you need strict minimal, set web_search.enabled = false.

1. Troubleshooting

• JSON parse error (Unexpected token ...)
  • Likely extra logs on stdio. Use node dist/cli.js, avoid npx.
• Auth error
  • Ensure OPENAI_API_KEY is provided.
• Timeout
  • Increase OPENAI_TIMEOUT_MS (e.g., 120000).
• 400 with Web Search
  • Caused by minimal effort + web search. It's auto-bumped to medium; alternatively set reasoning_effort=medium or disable web_search.

Tool: gpt5_query

Input schema (JSON):

{
  "query": "string",
  "model": "string?",
  "system": "string?",
  "reasoning_effort": "low|minimal|medium|high?",
  "verbosity": "low|medium|high?",
  "tool_choice": "auto|none?",
  "parallel_tool_calls": "boolean?",
  "max_output_tokens": "number?",
  "web_search": {
    "enabled": "boolean?",
    "search_context_size": "low|medium|high?"
  }
}

Example call (Inspector or client):

{
  "method": "tools/call",
  "params": {
    "name": "gpt5_query",
    "arguments": {
      "query": "Summarize the latest on X.",
      "verbosity": "low",
      "web_search": { "enabled": true, "search_context_size": "medium" }
    }
  }
}

Defaults and behavior

• model: defaults to OPENAI_MODEL (env). Example: gpt-5.
• system: optional. Sent as instructions.
• reasoning_effort: accepts low|minimal|medium|high. Internally low minimal
  • Constraint: when web_search.enabled=true and effort is minimal, it is auto-bumped to medium to satisfy OpenAI constraints.
• verbosity: defaults to DEFAULT_VERBOSITY (env). Sent as text.verbosity.
• tool_choice: default auto.
• parallel_tool_calls: default true.
• max_output_tokens: optional; omitted when not set.
• web_search.enabled: defaults to WEB_SEARCH_DEFAULT_ENABLED (env).
• web_search.search_context_size: defaults to WEB_SEARCH_CONTEXT_SIZE (env). Allowed: low|medium|high.

Environment variable mapping

• OPENAI_API_KEY (required)
• OPENAI_MODEL model default
• OPENAI_MAX_RETRIES OpenAI client
• OPENAI_TIMEOUT_MS OpenAI client
• REASONING_EFFORT reasoning_effort default (low|minimal|medium|high)
• DEFAULT_VERBOSITY verbosity default (low|medium|high)
• WEB_SEARCH_DEFAULT_ENABLED web_search.enabled default (true|false)
• WEB_SEARCH_CONTEXT_SIZE web_search.search_context_size default (low|medium|high)

Output shape

• On success: content: [{ type: "text", text: string }]
• On error: isError: true and a text item with Error: ...

Notes

• If the selected model does not support certain fields (e.g., verbosity), they are ignored.
• Keep API keys out of logs. Ensure .env is not committed.

License

MIT

日本語 (Japanese)

: gpt5_query

入力 (JSON):

{
  "query": "string",
  "model": "string?",
  "system": "string?",
  "reasoning_effort": "low|minimal|medium|high?",
  "verbosity": "low|medium|high?",
  "tool_choice": "auto|none?",
  "parallel_tool_calls": "boolean?",
  "max_output_tokens": "number?",
  "web_search": {
    "enabled": "boolean?",
    "search_context_size": "low|medium|high?"
  }
}

例 (Inspector ):

{
  "method": "tools/call",
  "params": {
    "name": "gpt5_query",
    "arguments": {
      "query": "Summarize the latest on X.",
      "verbosity": "low",
      "web_search": { "enabled": true, "search_context_size": "medium" }
    }
  }
}

既定値挙動

• model: 既定 OPENAI_MODEL環境変数例: gpt-5
• system: 任意OpenAI instructions 送信
• reasoning_effort: low|minimal|medium|high 受付内部的 low minimal 扱
  • 制約: web_search.enabled=true effort=minimal 場合OpenAI 制約合自動的 medium 引上
• verbosity: 既定 DEFAULT_VERBOSITY環境変数OpenAI text.verbosity 送信
• tool_choice: 既定 auto
• parallel_tool_calls: 既定 true
• max_output_tokens: 任意未指定場合送信
• web_search.enabled: 既定 WEB_SEARCH_DEFAULT_ENABLED環境変数
• web_search.search_context_size: 既定 WEB_SEARCH_CONTEXT_SIZE環境変数許容値: low|medium|high

環境変数

• OPENAI_API_KEY必須
• OPENAI_MODEL model 既定
• OPENAI_MAX_RETRIES OpenAI 設定
• OPENAI_TIMEOUT_MS OpenAI 設定
• REASONING_EFFORT reasoning_effort 既定low|minimal|medium|high
• DEFAULT_VERBOSITY verbosity 既定low|medium|high
• WEB_SEARCH_DEFAULT_ENABLED web_search.enabled 既定true|false
• WEB_SEARCH_CONTEXT_SIZE web_search.search_context_size 既定low|medium|high

出力形式

• 成功時: content: [{ type: "text", text: string }]
• 時: isError: true text Error: ...

注意

• 選択特定例: verbosity場合無視
• API 出力.env

MCP Server使方

Model Context Protocol (MCP) 標準入出力stdio動作純粋 JSON stdout 出力設計MCP Inspector / Claude Code / Claude Desktop 安全接続

前提

• Node.js 18+
• OpenAI API .env 環境変数設定

pnpm run build

1. 直接起動推奨

• : node
• 引数: dist/cli.js
• CWD: .env 読場合必須

例:

node dist/cli.js

1. Claude CodeVS Code 拡張追加

• VS Code Claude: Manage MCP Servers
• Add server次入力:
  • Name: gpt5-mcp
  • Command: node絶対可
  • Args: ["/絶対//gpt5-mcp-server/dist/cli.js"]導入済不要
  • Env一方:
    • AENV_FILE: ENV_FILE=/絶対//gpt5-mcp-server/.env
    • B明示指定: OPENAI_API_KEY``OPENAI_MODEL``OPENAI_TIMEOUT_MS``DEFAULT_VERBOSITY``REASONING_EFFORT``WEB_SEARCH_DEFAULT_ENABLED``WEB_SEARCH_CONTEXT_SIZE

1. Claude Desktop 追加
   設定例: macOS ~/Library/Application Support/Claude/claude_desktop_config.json編集以下追記

A: ENV_FILE 使

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/絶対//gpt5-mcp-server/dist/cli.js"],
      "env": {
        "ENV_FILE": "/絶対//gpt5-mcp-server/.env"
      }
    }
  }
}

B: 環境変数明示指定

{
  "mcpServers": {
    "gpt5-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/絶対//gpt5-mcp-server/dist/cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-5",
        "OPENAI_TIMEOUT_MS": "120000",
        "DEFAULT_VERBOSITY": "medium",
        "REASONING_EFFORT": "low",
        "WEB_SEARCH_DEFAULT_ENABLED": "false",
        "WEB_SEARCH_CONTEXT_SIZE": "medium"
      }
    }
  }
}

1. CLI 利用

• bin 含
• : npm link 後 gpt5-mcp-server
• 公開後: npm i -g gpt5-mcp-server gpt5-mcp-server
• 直接実行: node /絶対//gpt5-mcp-server/dist/cli.js

1. Web Search 関注意

• OpenAI 制約web_search_preview reasoning.effort = minimal 併用
• 本 web_search.enabled = true 場合自動的 effort medium 引上呼出
• minimal 厳格使場合web_search.enabled = false

• JSON Unexpected token ...
  • stdio 余計出力混可能性node dist/cli.js 使npx 避
  • .env 読込既抑止済
• 認証
  • OPENAI_API_KEY 正渡確認
• • OPENAI_TIMEOUT_MS 増例: 120000
• Web Search 400
  • reasoning.effort=minimal web_search 併用不可原因自動的 medium 上明示的 medium 指定web_search 無効化