MCP server for building with the OpenAI API: probe-verified model reference, request linter for Responses and Chat Completions, cost estimates, scaffolding, plus live responses, embeddings, batches, files, vector stores, speech and images.
An MCP server for building with the OpenAI API. It gives an agent two things:
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.Not affiliated with OpenAI. "OpenAI" and "GPT" are trademarks of OpenAI.
Requires Node.js 20 or newer.
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
Register it (use the absolute path of server.mjs):
# Claude Code
claude mcp add --transport stdio --env OPENAI_API_KEY=$OPENAI_API_KEY openai-api -- node /abs/path/openai-api-mcp/server.mjs
# Codex: ~/.codex/config.toml
[mcp_servers.openai-api]
command = "node"
args = ["/abs/path/openai-api-mcp/server.mjs"]
env_vars = ["OPENAI_API_KEY"]
// 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 |
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.
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.
model_reference
reports the observation date. Re-run the probes when in doubt.list_models but not rule-probed. Dated snapshots are assumed to behave
like their alias.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.gpt-5.3-codex, chat-latest): cost tools return an
error for them rather than a guess.response.usage and your invoice.recommend_model is a heuristic. Evaluate on your own data.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.
Installing only copies or configures. Nothing is executed for you. The Skills CLI verifies the checksum before writing files.
Select a file to preview it. Files are shown as plain text and never executed.
probes/build-knowledge.mjstest/run-scaffolds.mjsStatic checks are advisory. They never certify that a package is safe. Compatibility entries are publisher claims unless marked verified.
| Version | Published | Size | SHA-256 | State |
|---|---|---|---|---|
| 1.0.0latest | Nov 10, 2026 | 83 kB | 573fc176c811… | published |
MCP server that drives Safari on macOS through AppleScript: navigation, reading, forms, uploads, downloads with the page's session, screenshots. Works in its own window, with domain policy and sensitive-field guards.
MCP server for building with the Claude API: probe-verified model reference, request linter and fixer, cost estimates, agent scaffolding, plus live messages, token counting, batches, files and Managed Agents.
Dependency-free local MCP server over stdio with a single echo tool, for testing client configuration.