mcp-openai-platform

A local MCP (Model Context Protocol) server exposing the OpenAI platform REST API as tools — files, fine-tuning, inference, images, audio, batch, and organization usage/costs.

Built for this project after doing a full fine-tuning run by hand with curl; the tool descriptions encode the gotchas found along the way (see Notable behaviours) so they don't have to be rediscovered.

What this is (and isn't)

This is: a stdio MCP server that your MCP client (Claude Code, etc.) runs locally. The client calls these tools; the tools call OpenAI's REST API.

Claude Code (MCP client)
  → mcp-openai-platform (local stdio server)
    → https://api.openai.com/v1/...

This is not: a server for OpenAI's models to call. OpenAI's own docs on MCP and connectors and Secure MCP Tunnels describe the opposite direction — the Responses API consuming a remote MCP server over the network, with OAuth and tunnels. None of that applies here; this is a plain local server and needs no OAuth, no tunnel, no public URL.

Related MCP server: OpenAI API MCP Server

Install

Requires Node.js 18+ (uses built-in fetch and FormData; developed on Node 24).

cd mcp-openai
npm install
npm run build          # compiles src/ → dist/

Verify the build produced dist/index.js:

ls dist/               # index.js, openai-client.js

The server is now runnable but does nothing on its own — it speaks MCP over stdio and needs a client to drive it. Register it using one of the methods below.

Adding it to an agent / MCP client

The server is a stdio MCP server, so registration is the same shape everywhere: command = node, args = absolute path to dist/index.js, env = your API keys.

Use the absolute path — MCP clients don't reliably resolve relative paths, and the working directory at launch isn't guaranteed.

Claude Code — CLI (quickest)

claude mcp add openai-platform \
  --env OPENAI_API_KEY=sk-proj-... \
  --env OPENAI_ADMIN_API_KEY=sk-admin-... \
  -- node /absolute/path/to/mcp-openai/dist/index.js

On Windows, use the Windows-style absolute path:

claude mcp add openai-platform ^
  --env OPENAI_API_KEY=sk-proj-... ^
  -- node E:\wamp64\www\Ticketing_new\mcp-openai\dist\index.js

Add --scope project to write it into the project's .mcp.json (shared with the repo) instead of your personal config. Then:

claude mcp list           # confirm it's registered
claude mcp get openai-platform

Claude Code — project config file

Edit .mcp.json at the project root (this is what this project uses):

{
  "mcpServers": {
    "openai-platform": {
      "type": "stdio",
      "command": "node",
      "args": ["E:\\wamp64\\www\\Ticketing_new\\mcp-openai\\dist\\index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_ADMIN_API_KEY": "sk-admin-..."
      }
    }
  }
}

Note the escaped backslashes — .mcp.json is JSON, so Windows paths need \\. Forward slashes also work on Windows if you prefer.

Claude Desktop

Edit the config file directly, then fully quit and reopen the app:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Same mcpServers block as above.

Other MCP clients

Anything that speaks MCP over stdio works — Cursor, Windsurf, Zed, Continue, or a custom client built on the MCP SDK. The config key names vary slightly by app, but all of them need the same three things:

command: node
args:    ["<absolute path>/mcp-openai/dist/index.js"]
env:     { OPENAI_API_KEY: "...", OPENAI_ADMIN_API_KEY: "..." }

Verifying it works

After registering, restart the client and ask it to list your fine-tuning jobs, or check the tool list directly. In Claude Code:

/mcp

You should see openai-platform as connected with 31 tools. If it shows as failed, see Troubleshooting.

Restart the client after every rebuild — the server process is spawned at client startup, so a recompiled dist/ won't be picked up until it relaunches.

Troubleshooting

Why a local path instead of npm

Deliberate. Publishing would mean a version bump + republish for every tweak, and npx -y <pkg> re-resolves from the registry on each launch. A direct node dist/index.js path skips all of that, and the project-specific guidance baked into tool descriptions isn't meaningful to anyone else. If this ever needs to run on other machines, publishing is a small step to take then.

Authentication — two keys, two tiers

OPENAI_API_KEY is required — the server exits at startup without it. OPENAI_ADMIN_API_KEY is optional; only the three org tools need it, and they return a clear error explaining what's missing if it isn't set.

These are genuinely different credential types. A project key — even one with full permissions inside its project — gets 403 Missing scopes: api.usage.read on the /organization/* endpoints. That's by design, not a misconfiguration.

Tools (31)

Files

Models

Fine-tuning

Inference

Images

openai_generate_image, openai_edit_image (local file paths + optional mask), openai_create_image_variation (dall-e-2 only, per OpenAI).

Audio

Batch

openai_create_batch, openai_get_batch, openai_list_batches, openai_cancel_batch. Discounted vs. synchronous calls; results arrive within the completion window (default 24h).

Organization — requires admin key

Notable behaviours

Things that cost real debugging time and are now encoded in the tool descriptions:

• No fine-tuning usage endpoint exists. OpenAI provides /organization/usage/{completions,embeddings,images,moderations,audio_*,vector_stores,…} — but nothing for fine-tuning training. Training cost only appears folded into the daily total from openai_get_org_costs, so you infer it from a spike on the training day.

• Fine-tuning result files may come back base64-encoded. The training-metrics CSV downloaded raw looks like garbage and wc -l reports 0 lines. openai_download_file_content takes decode_base64: true for this.

• Bare model aliases can reject fine-tuning. gpt-4o-mini returned model_not_available, while the dated snapshot gpt-4o-mini-2024-07-18 was fine. Use openai_list_models with a ft: filter to see which base models already have working fine-tunes on the account.

• insufficient_quota (429) is an account problem, not a code problem. If openai_list_models works but every inference call 429s, it's billing/balance — not scopes, not rate limits. A single fine-tuning job can exhaust a small balance and take unrelated production traffic down with it.

• Streaming is intentionally not exposed. An MCP tool result is a single payload, so a streamed body would only be reassembled before returning.

• TLS note (PHP callers, not this server). Node's fetch uses the system trust store and works fine. The PHP scripts in ../pnr_finetune/ needed an explicit CA bundle because that install has curl.cainfo unset — the fix there was CURLOPT_CAINFO, not disabling verification.

Cost

openai_create_finetune_job spends money. Confirmed against a real bill: fine-tuning gpt-4o-2024-08-06 is $25 per 1M trained tokens — a 1,603,698-token job produced a $40.09 charge against a $40.15 daily total (the remainder being that day's inference).

Check the account's balance/limit before starting a job. Inference tools cost per-token at each model's own rate.

Development

npm run build     # compile once
npm run dev       # tsc --watch

Adding a tool means four edits, all in the obvious places:

1. A method on OpenAIClient in src/openai-client.ts

2. A zod schema in src/index.ts

3. An entry in the TOOLS array

4. A case in dispatch()

Rebuild and restart the MCP client to pick up changes.

Manual smoke test

node -e "
const {spawn}=require('child_process');
process.env.OPENAI_API_KEY='sk-...';
const p=spawn('node',['dist/index.js'],{env:process.env});
let b=''; p.stdout.on('data',d=>b+=d);
setTimeout(()=>p.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'t',version:'1'}}})+'\n'),300);
setTimeout(()=>p.stdin.write(JSON.stringify({jsonrpc:'2.0',id:2,method:'tools/list',params:{}})+'\n'),800);
setTimeout(()=>{console.log(b);p.kill();},2000);
"

Security

• .mcp.json holds keys in plaintext. It matches how the other servers in this project are configured, but treat the file accordingly and keep it out of anywhere it'd be shared.

• Never paste an API key — especially an Admin key — into a chat or terminal session that gets logged. If that happens, rotate it immediately at the admin-keys page; assume it's compromised regardless of how briefly it was used.

• openai_delete_file and openai_cancel_* are destructive and take effect immediately.

Related

• ../pnr_finetune/ — the dataset builder and evaluation scripts this server was extracted from

• ../docs/openai-fine-tuning-guide.md — full walkthrough of the fine-tuning run, with curl equivalents

• ../docs/openai-fine-tuning-general-guide.md — task-agnostic fine-tuning playbook