# openai-api-mcp

An MCP server for building with the OpenAI API. It gives an agent two things:

Knowledge that was measured, not remembered. OpenAI parameter rules differ per model and per API: reasoning effort levels vary, temperature is accepted only in specific conditions, several models are not served on Chat Completions. This server ships a knowledge base built by sending 55 request shapes to each of 29 text models and recording what the API accepted. A linter turns that into findings and fixes before a request is sent.
Hands on the API. Responses, token counting, structured extraction, embeddings, moderation, batches, files, vector stores, speech and images — with a spend guard, lint-before-send, confirmation on destructive calls and file access confined to one directory.

Not affiliated with OpenAI. "OpenAI" and "GPT" are trademarks of OpenAI.

# Install

Requires Node.js 20 or newer.

bash

skills download @spboucher/openai-api-mcp --extract ./openai-api-mcp   # or download the archive and verify its SHA-256
cd openai-api-mcp
npm ci --omit=dev   # installs openai, @modelcontextprotocol/sdk and zod from the lockfile
npm test            # offline tests, no key needed

bash

# Claude Code
claude mcp add --transport stdio --env OPENAI_API_KEY=$OPENAI_API_KEY openai-api -- node /abs/path/openai-api-mcp/server.mjs

toml

# Codex: ~/.codex/config.toml
[mcp_servers.openai-api]
command = "node"
args = ["/abs/path/openai-api-mcp/server.mjs"]
env_vars = ["OPENAI_API_KEY"]

json

// Cursor: .cursor/mcp.json
{ "mcpServers": { "openai-api": { "type": "stdio", "command": "node", "args": ["/abs/path/openai-api-mcp/server.mjs"], "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" } } } }

The key is optional: the eleven offline tools work without it.

Variable	Purpose	Default
`OPENAI_API_KEY`	Key for the live tools. Read from the environment, never returned in any output	none
`OPENAI_API_MCP_MAX_OUTPUT_TOKENS`	Spend guard: largest output cap the server will send	32000
`OPENAI_API_MCP_FILE_ROOT`	Only directory the file, speech and image tools may read or write	working directory

# Tools

Offline (no key, no cost)

Tool	What it does
`model_reference`	Context window, output cap, prices, reasoning effort levels, when `temperature` is accepted, Chat Completions support, hosted tools
`recommend_model`	Model and reasoning effort for a task, honouring hard requirements
`lint_request`	Findings for a Responses or Chat Completions request, each with a fix and the API error text observed
`fix_request`	Applies the mechanical fixes and reports what changed
`chat_to_responses`	Converts a Chat Completions request to the Responses API
`migrate_request`	Rewrites a request for another model (converting the API when the target is Responses-only)
`estimate_cost`, `compare_costs`	Cost with cached input, batch, fast mode and long-context rates
`scaffold_app`	Runnable starters: single call, streaming, structured output, function loop, conversation state, web search, Agents SDK, embeddings, batch — TypeScript or Python
`explain_error`	Maps a status, code or message to a cause and a fix
`feature_guide`	Short guidance on 15 topics

Live

Tool	Notes
`list_models`, `count_tokens`, `moderate`	Free
`create_response`	Billed. Linted first; nothing is sent if the API would reject it. `auto_fix` applies fixes. Sends Chat Completions when the body has `messages`
`extract_structured`	Billed. Returns parsed JSON matching your schema (made strict automatically)
`get_response`, `cancel_response`, `delete_response`	Stored and background responses
`create_embeddings`	Returns dimensions, usage and a similarity matrix; vectors only on request
`batch_create`, `batch_get`, `batch_list`, `batch_results`, `batch_cancel`	Builds and uploads the JSONL for you
`file_upload`, `file_list`, `file_get`, `file_delete`	Uploads confined to the file root
`vector_store_create`, `vector_store_add`, `vector_store_search`, `vector_store_list`, `vector_store_delete`	Retrieval; stores expire after 7 days by default
`text_to_speech`, `transcribe_audio`, `generate_image`	Billed. Read and write only inside the file root; never overwrite

Destructive tools refuse to act without confirm: true.

# What "verified" means here

probes/probe.mjs sends small requests to every probed model. Raw results: probes/matrix.json. probes/build-knowledge.mjs derives knowledge.json from them, from the official pricing page and from the official model pages (probes/model-pages.json).
test/offline.test.mjs asserts that the linter predicts accept/reject exactly as the API did for all 1,594 recorded outcomes, that the fixer yields acceptable requests, and that the chat→responses converter yields valid requests for every chat probe.
test/run-scaffolds.mjs executes every scaffold template against the API in both languages.
test/live.test.mjs drives the server through the MCP protocol with the official client: responses, function calling, stored state, vision, structured extraction, web search, embeddings, moderation, files, vector-store retrieval, speech round trip, image generation, batches.

Refresh the knowledge base yourself: OPENAI_API_KEY=… npm run probe, then npm test. Probing every model, including the -pro models, costs a few dollars.

# Limits — read these

A snapshot. Behaviour was observed on 2026-11-10 (UTC). APIs change; model_reference reports the observation date. Re-run the probes when in doubt.
Only text models visible to the probing key. Audio, image, realtime, embedding and moderation models are listed by list_models but not rule-probed. Dated snapshots are assumed to behave like their alias.
Batch results were not verified end to end on a multi-request batch. Batches submitted while testing stayed in_progress for over half an hour. Creating, polling, listing and cancelling were verified; batch_results parsing was checked against the documented output format only.
Not probed: computer use, the Realtime API, fine-tuning, the Assistants API, Azure OpenAI.
Two models have no official price (gpt-5.3-codex, chat-latest): cost tools return an error for them rather than a guess.
Cost figures are estimates from list prices; hosted-tool, image and audio charges are not included. Check response.usage and your invoice.
recommend_model is a heuristic. Evaluate on your own data.
Model output, transcripts and retrieved text returned by tools are untrusted data.

# Security

The server reads the key from its environment and scrubs key-, organisation- and project-shaped strings from error messages. It executes no model output and opens no listening port. Local file access is limited to OPENAI_API_MCP_FILE_ROOT: reads for uploads and transcription, writes for speech and images, never overwriting an existing file.

spb llm-api-toolkits