Repository Public Research preview
1# openai-api-mcp23An MCP server for building with the OpenAI API. It gives an agent two things:451. **Knowledge that was measured, not remembered.** OpenAI parameter rules differ per model and per6 API: reasoning effort levels vary, `temperature` is accepted only in specific conditions,7 several models are not served on Chat Completions. This server ships a knowledge base built by8 sending 55 request shapes to each of 29 text models and recording what the API accepted. A9 linter turns that into findings and fixes before a request is sent.102. **Hands on the API.** Responses, token counting, structured extraction, embeddings, moderation,11 batches, files, vector stores, speech and images — with a spend guard, lint-before-send,12 confirmation on destructive calls and file access confined to one directory.1314Not affiliated with OpenAI. "OpenAI" and "GPT" are trademarks of OpenAI.1516## Install1718Requires Node.js 20 or newer.1920```bash21skills download @spboucher/openai-api-mcp --extract ./openai-api-mcp # or download the archive and verify its SHA-25622cd openai-api-mcp23npm ci --omit=dev # installs openai, @modelcontextprotocol/sdk and zod from the lockfile24npm test # offline tests, no key needed25```2627Register it (use the absolute path of `server.mjs`):2829```bash30# Claude Code31claude mcp add --transport stdio --env OPENAI_API_KEY=$OPENAI_API_KEY openai-api -- node /abs/path/openai-api-mcp/server.mjs32```3334```toml35# Codex: ~/.codex/config.toml36[mcp_servers.openai-api]37command = "node"38args = ["/abs/path/openai-api-mcp/server.mjs"]39env_vars = ["OPENAI_API_KEY"]40```4142```json43// Cursor: .cursor/mcp.json44{ "mcpServers": { "openai-api": { "type": "stdio", "command": "node", "args": ["/abs/path/openai-api-mcp/server.mjs"], "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" } } } }45```4647The key is optional: the eleven offline tools work without it.4849| Variable | Purpose | Default |50|---|---|---|51| `OPENAI_API_KEY` | Key for the live tools. Read from the environment, never returned in any output | none |52| `OPENAI_API_MCP_MAX_OUTPUT_TOKENS` | Spend guard: largest output cap the server will send | 32000 |53| `OPENAI_API_MCP_FILE_ROOT` | Only directory the file, speech and image tools may read or write | working directory |5455## Tools5657**Offline (no key, no cost)**5859| Tool | What it does |60|---|---|61| `model_reference` | Context window, output cap, prices, reasoning effort levels, when `temperature` is accepted, Chat Completions support, hosted tools |62| `recommend_model` | Model and reasoning effort for a task, honouring hard requirements |63| `lint_request` | Findings for a Responses or Chat Completions request, each with a fix and the API error text observed |64| `fix_request` | Applies the mechanical fixes and reports what changed |65| `chat_to_responses` | Converts a Chat Completions request to the Responses API |66| `migrate_request` | Rewrites a request for another model (converting the API when the target is Responses-only) |67| `estimate_cost`, `compare_costs` | Cost with cached input, batch, fast mode and long-context rates |68| `scaffold_app` | Runnable starters: single call, streaming, structured output, function loop, conversation state, web search, Agents SDK, embeddings, batch — TypeScript or Python |69| `explain_error` | Maps a status, code or message to a cause and a fix |70| `feature_guide` | Short guidance on 15 topics |7172**Live**7374| Tool | Notes |75|---|---|76| `list_models`, `count_tokens`, `moderate` | Free |77| `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` |78| `extract_structured` | Billed. Returns parsed JSON matching your schema (made strict automatically) |79| `get_response`, `cancel_response`, `delete_response` | Stored and background responses |80| `create_embeddings` | Returns dimensions, usage and a similarity matrix; vectors only on request |81| `batch_create`, `batch_get`, `batch_list`, `batch_results`, `batch_cancel` | Builds and uploads the JSONL for you |82| `file_upload`, `file_list`, `file_get`, `file_delete` | Uploads confined to the file root |83| `vector_store_create`, `vector_store_add`, `vector_store_search`, `vector_store_list`, `vector_store_delete` | Retrieval; stores expire after 7 days by default |84| `text_to_speech`, `transcribe_audio`, `generate_image` | Billed. Read and write only inside the file root; never overwrite |8586Destructive tools refuse to act without `confirm: true`.8788## What "verified" means here8990- `probes/probe.mjs` sends small requests to every probed model. Raw results: `probes/matrix.json`.91 `probes/build-knowledge.mjs` derives `knowledge.json` from them, from the official pricing page92 and from the official model pages (`probes/model-pages.json`).93- `test/offline.test.mjs` asserts that the linter predicts accept/reject **exactly** as the API did94 for all 1,594 recorded outcomes, that the fixer yields acceptable requests, and that the95 chat→responses converter yields valid requests for every chat probe.96- `test/run-scaffolds.mjs` executes every scaffold template against the API in both languages.97- `test/live.test.mjs` drives the server through the MCP protocol with the official client:98 responses, function calling, stored state, vision, structured extraction, web search, embeddings,99 moderation, files, vector-store retrieval, speech round trip, image generation, batches.100101Refresh the knowledge base yourself: `OPENAI_API_KEY=… npm run probe`, then `npm test`. Probing102every model, including the `-pro` models, costs a few dollars.103104## Limits — read these105106- **A snapshot.** Behaviour was observed on 2026-11-10 (UTC). APIs change; `model_reference`107 reports the observation date. Re-run the probes when in doubt.108- **Only text models visible to the probing key.** Audio, image, realtime, embedding and moderation109 models are listed by `list_models` but not rule-probed. Dated snapshots are assumed to behave110 like their alias.111- **Batch results were not verified end to end on a multi-request batch.** Batches submitted while112 testing stayed `in_progress` for over half an hour. Creating, polling, listing and cancelling113 were verified; `batch_results` parsing was checked against the documented output format only.114- **Not probed:** computer use, the Realtime API, fine-tuning, the Assistants API, Azure OpenAI.115- **Two models have no official price** (`gpt-5.3-codex`, `chat-latest`): cost tools return an116 error for them rather than a guess.117- **Cost figures are estimates** from list prices; hosted-tool, image and audio charges are not118 included. Check `response.usage` and your invoice.119- `recommend_model` is a heuristic. Evaluate on your own data.120- Model output, transcripts and retrieved text returned by tools are untrusted data.121122## Security123124The server reads the key from its environment and scrubs key-, organisation- and project-shaped125strings from error messages. It executes no model output and opens no listening port. Local file126access is limited to `OPENAI_API_MCP_FILE_ROOT`: reads for uploads and transcription, writes for127speech and images, never overwriting an existing file.128