gpt5

GPT-5 MCP Server exposes a gpt5_query tool that enables GPT-5 inference via the OpenAI API, with optional Web Search Preview and per-call overrides for verbosity, reasoning effort, tool usage, and parallel tool calls. The server speaks the MCP protocol over stdio and outputs pure JSON to stdout, making it compatible with MCP clients such as Claude Code and Claude Desktop. To use it, run the MCP server (via node dist/cli.js) and connect your MCP client to the server's stdio stream. The primary tool is gpt5_query, which accepts a JSON payload describing the query, desired model, system prompt, reasoning effort, verbosity, and optional web_search settings. Per-call overrides allow you to adjust how verbose the answer should be and how much reasoning the model should perform, as well as whether to perform web searches for up-to-date information. The server also supports configuring defaults through environment variables so you can tailor behavior without changing requests.

Prerequisites: Node.js 18+ environment, a valid OpenAI API key. Install dependencies and build the TypeScript project, then run the server.

Steps:

1. Install dependencies

• pnpm i (or npm i / yarn)

2. Configure environment variables (example .env or in your shell)

• 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

3. Build the project

pnpm run build

4. Run the server (MCP config assumes node dist/cli.js)

pnpm start

5. Optional development mode

pnpm run dev

6. Verify MCP client connectivity (example using Claude Code/Claude Desktop integration as described in the README).

Tips and notes:

• The gpt5_query tool supports per-call overrides for parameters like verbosity (low|medium|high), reasoning_effort (low|minimal|medium|high), tool_choice (auto|none), and parallel_tool_calls. If web_search.enabled is true, reasoning_effort will be bumped to medium to satisfy OpenAI constraints; you can adjust by setting reasoning_effort explicitly or disabling web search.
• Web search and minimal effort may not combine; the README notes that web_search_preview cannot be used with minimal reasoning.
• Ensure OPENAI_API_KEY is kept out of logs and consider using a dedicated .env file loaded at runtime.
• When debugging JSON parse errors, prefer running the CLI directly (node dist/cli.js) to avoid extra logs that might appear when using npx.
• If you need to customize defaults per deployment, use the environment variable mappings described in the README to influence model, verbosity, and web search behavior.