OpenAI MCP Extensions
OpenAI ships SKILL.md agent-skill packaging inside its ChatGPT plugin SDK, and every claim we tested held.
This is the repo where OpenAI's ChatGPT plugin platform absorbs agent-skill packaging: a 1,834-line extension spec, dual TypeScript and Python SDKs on npm and PyPI, and a demo plugin whose two SKILL.md files ride a 20-tool MCP server. Our full build-package-run pipeline passed every functional probe, including both negative cases. Install it if you build for ChatGPT or Codex; everyone else should read the spec and wait for the ecosystem rails to catch up.
$npm install @openai/mcp-extensions
server + app subpaths
$pip install openai-mcp-extensions
needs mcp>=2.0.0b2 (beta)
$install Bits & Bolts Remote from the ChatGPT plugin directory
linked in the repo README
install if
- ChatGPT or Codex plugin builders. This is the canonical SDK, spec, and reference implementation for the surface, published by the platform owner with both language runtimes live on day one.
- MCP server developers wanting native-feeling ChatGPT integration. Sidebar entrypoints, structured settings, at-mentions, and form elicitation are exactly the gaps plain MCP leaves open on ChatGPT.
- Anyone tracking agent-skill format convergence. The
.agents/plugins/marketplace.jsonplus SKILL.md layout inside an OpenAI repo is the clearest signal yet that plugin platforms are absorbing the agent-skill packaging convention, and the bits-and-bolts plugin is its most complete worked example.
skip if
- Claude Code, Hermes, Cursor, and other-host users looking for installable skills. The SKILL.md files are ChatGPT runtime contracts, the repo is not on skills.sh, and nothing here installs into non-OpenAI skill directories.
- Teams standardized on stable MCP Python 1.x. The beta
mcp>=2.0.0b2pin makes adoption a runtime migration decision, not a drop-in. - Anyone needing production stability this quarter. Version 0.1.0, two days of public history, a platform matrix with many "not supported" cells, and an open transport bug report: read and prototype now, depend later.
What It Does
OpenAI MCP Extensions is the official early-access toolkit for building ChatGPT plugins on top of MCP. It contains three things: a 1,834-line specification (docs/spec.md) defining ChatGPT-specific MCP extensions such as sidebar entrypoints, custom file viewers, composer at-mentions, structured settings, plugin onboarding, model-context sharing, and a thumbnail-capable form elicitation protocol; a TypeScript SDK (@openai/mcp-extensions on npm, with /server and /app subpath exports) and a Python SDK (openai-mcp-extensions on PyPI); and bits-and-bolts, a "kitchen-sink" example plugin that bundles a CAD parts library, a 3D viewer, a 20-tool MCP server, and two SKILL.md agent skills inside a .agents/plugins/marketplace.json manifest. The audience is developers building plugins for ChatGPT (Desktop, Work web, iOS, Android) and Codex. For the agent-skills ecosystem the repo is a landmark: it is the first OpenAI repository to ship SKILL.md packaging and an .agents/ plugin manifest, which means the largest vendor's consumer plugin surface now speaks the agent-skill format natively. At review time the repo was two days old, at 344 stars and 16 forks (API-verified), with 6 open issues and pull requests.
The Good
Every quantitative claim we checked held exactly. The plugin README claims a bundled library of 36 photo-referenced parts; the live cad.listParts tool returned exactly 36 structured records. The onboarding SKILL.md documents a settings contract with a units enum of mm/in, a showGrid boolean, and a defaultView field; the live settings.read tool returned that schema verbatim, including the enum values. The packaging claim ("requires Node.js but no dependency installation, Python, Blender, or SDK checkout") verified structurally: the packaged output is a 59MB directory whose dist/server.js is a single bundled file with all dependencies inlined and no node_modules anywhere, and it served a full MCP session from a bare directory on stock Node 24.
The functional surface is unusually clean for a launch-week repo. Our 8-point probe suite passed 8 of 8: initialize handshake advertising the OpenAI-specific extensions and experimental capabilities, 20 tools enumerated (17 cad.* tools plus SDK-provided settings.read, settings.update, and search_mentions), 38 resources across ui://, cad-resource://, and mcp:// schemes, a search call returning the right part, and two negative cases that both failed the way they should (unknown tool returns MCP error -32602: Tool not found; bogus part id returns isError: true with "CAD library part was not found"). Nothing hung, nothing crashed the server, and error text is specific rather than generic.
The release engineering is documented to a degree most repos never reach. docs/publishing.md (55 lines) lays out release-please per package, OIDC trusted publishing to PyPI and npm with no long-lived tokens, environment-gated publish switches, provenance handling rules, and a rehearsal workflow. Both SDKs were actually published the day before this review: @openai/mcp-extensions 0.1.0 on npm (created 2026-09-29T17:26Z) and openai-mcp-extensions 0.1.0 on PyPI, which installed cleanly into a fresh venv and exposed 40 typed symbols covering entrypoints, settings, mentions, forms, and UI metadata.
The build is fast and reproducible. pnpm install --frozen-lockfile completed in 15.6 seconds, the workspace build (TypeScript compile plus a Vite build of the plugin, 104 modules) finished in seconds, and the plugin repackaging step took 131ms. Lint runs at --max-warnings 0 with ESLint 9, Prettier, publint, and pyright/ruff wired into the check script, and the plugin ships real unit tests (inspection.test.ts, catalog.test.ts, catalog-import.test.ts).
The Bad
The documented build path assumes pnpm and never tells you how to get it. On a machine with stock Node 24 and nothing else, the plugin README's first command (pnpm install --frozen-lockfile) fails with pnpm: command not found. The recovery exists, corepack resolves the pinned pnpm@11.19.0 from the packageManager field, but neither the root README nor the plugin README mentions corepack, npm's global-install friction, or any bootstrap step. This is the only failure in our fresh-environment run (5 of 6 checks passed).
The Python SDK requires a beta of the MCP runtime. Its dependency list pins mcp>=2.0.0b2, a pre-release of the official MCP Python SDK. Servers built on the stable 1.x line cannot adopt these extensions without also moving to a beta runtime, and the Python README's install section does not flag the constraint; you only meet it at dependency-resolution time. For an early-access SDK this is defensible, but it is the single biggest adoption tax for Python plugin authors.
The agent-skill packaging is ChatGPT-native, not ecosystem-native. The repo is absent from the skills.sh registry (our owner and exact-name queries returned zero entries), and the two SKILL.md files are thin runtime contracts, 8 and 29 lines, that tell the ChatGPT plugin host when to call cad.pickFile or how to run onboarding. They are not standalone teachable skills, and there is no install path for Claude Code, Hermes, Cursor, or any non-OpenClaw-adjacent host. If you found this repo through its SKILL.md files, note that the skills only activate inside OpenAI's plugin runtime.
The source checkout is asset-heavy. A shallow clone weighs 185MB: 81MB of git objects, 49MB of demo GIFs and screenshots under resources/, 46MB of GLB and STL CAD models inside the plugin, against roughly 8,800 lines of TypeScript and Python source plus 1,834 lines of spec. The models are load-bearing (the packaged plugin needs them), but the GIFs exist twice over (resources/ and docs/resources/), which inflates every clone for documentation's sake.
Early-access limits are real and mapped. The spec's platform matrix marks file entrypoints, local file opening, file resources, and composer at-mentions as Desktop-only, with classic ChatGPT excluded outright from the web column. Versioning is 0.1.0 across the board with the new tag scheme (python-v*/node-v*) not yet exercised, and there is one open bug report worth tracking: listener errors in the transport silently block other listeners.
Smoke Test Results
We ran three host-based passes on macOS (aarch64), Node v24.13.1, testing the full clone-build-package-run pipeline against commit e314720 (2026-09-29). No Linux sandbox was available, so the sandbox image is the host; all scripts and logs ship in the repo.
Run A. Fresh sandbox, no deps preinstalled
$ git clone --depth 1 https://github.com/openai/mcp-extensions.git
β
PASS: clone (185MB shallow)
$ node --version
β
PASS: v24.13.1 (engines requires >=22)
$ pnpm install --frozen-lockfile
β FAIL: pnpm: command not found (README build step 1, bare machine)
$ corepack pnpm --version
β
PASS: 11.19.0 resolves from the pinned packageManager field
$ npm view @openai/mcp-extensions version
β
PASS: 0.1.0 published on npm
$ curl -sf https://pypi.org/pypi/openai-mcp-extensions/json
β
PASS: 0.1.0 published on PyPI
Pass rate: 5 of 6. The single failure is the undocumented pnpm prerequisite; corepack recovers it, but nothing in the docs says so.
Run B. Sandbox with deps preinstalled
$ pnpm install --frozen-lockfile
β
PASS: 15.6s, frozen lockfile honored
$ pnpm build
β
PASS: tsc SDK build + vite plugin build
$ node scripts/build.mjs --plugin-dir /tmp/mcpext-bnb-pkg
β
PASS: plugin packaged
$ ls dist/server.js .mcp.json .codex-plugin/plugin.json skills/*/SKILL.md
β
PASS: all five packaging artifacts present
$ ls node_modules
β
PASS: absent (self-contained package claim holds, 59MB)
Pass rate: 11 of 11. This is the canonical install verdict: with pnpm available (either version 11.19.0 pinned via corepack or 12.8.1 from npm latest), the documented pipeline completes start to finish.
Run C. Functional verification (does it do what it claims?)
$ (MCP initialize over stdio, packaged server)
β
PASS: serverInfo bits-and-bolts 0.1.0, capabilities include extensions + experimental
$ tools/list
β
PASS: 20 tools (17 cad.* + settings.read/settings.update/search_mentions)
$ cad.listParts {}
β
PASS: 36 structured parts, README claims exactly 36
$ cad.search {"query":"star"}
β
PASS: returns "Star keycap (1U)"
$ settings.read {}
β
PASS: schema matches the onboarding SKILL.md contract (units mm/in, showGrid, defaultView)
$ cad.doesNotExist {}
β
PASS: clean MCP -32602 "Tool not found" error
$ cad.readPart {"partId":"bogus-part-xyz"}
β
PASS: isError with "CAD library part was not found: bogus-part-xyz"
$ resources/list
β
PASS: 38 resources across ui://, cad-resource://, mcp:// schemes
Functional pass rate: 8 of 8, plus a Python leg (PyPI install, 40 exports enumerated, beta mcp>=2.0.0b2 pin confirmed, app submodule correctly absent since app extensions are Node-only).
What the runs tell you
The repo does what it says at every layer we could reach from a terminal: install, build, package, serve, and error handling all behave as documented, with claim-versus-output agreement down to exact part counts and schema fields. What a terminal cannot reach is the host side: the ChatGPT sidebar, file viewer, at-mentions, and form elicitation only activate inside ChatGPT or Codex clients, so those surfaces are verified here only through the protocol objects the server exposes (capabilities, resource metadata, elicitation schemas), not through a live ChatGPT session.
Setup Walkthrough
- Install Node 22 or later (engines floor; we used 24.13.1). Enable a pnpm: either
corepack enable(resolves the repo's pinned 11.19.0) ornpm install -g pnpm. git clone --depth 1 https://github.com/openai/mcp-extensions.git(185MB; the bulk is demo GIFs and CAD models, not code).- From the repo root:
pnpm install --frozen-lockfile, thenpnpm build. About 20 seconds total on an M-series Mac. - To try the example plugin:
cd plugins/bits-and-bolts && node scripts/build.mjs --plugin-dir /tmp/bits-and-bolts. The output directory is the distributable plugin: copy it whole, it needs only Node at runtime. - To use the SDKs in your own server:
npm install @openai/mcp-extensions(TypeScript) orpip install openai-mcp-extensions(Python). The Python package pulls themcp>=2.0.0b2beta, so pin deliberately. - The zero-build path is the ChatGPT plugin directory: install "Bits & Bolts Remote" from the link in the README to see the extensions running without touching a compiler.
Gotcha: the .mcp.json inside the packaged plugin runs node ./dist/server.js with cwd set to the package root; run it from elsewhere and the relative asset paths break. The skills only trigger inside OpenAI hosts; installing the SKILL.md files into Claude Code or Hermes gives you the text without the runtime.
Alternatives
- Plain MCP SDKs (modelcontextprotocol/python-sdk, typescript-sdk) - build a standard MCP server that works across every host, giving up the ChatGPT-native surfaces this repo adds.
- MCP Apps spec (modelcontextprotocol/ext-apps) - the vendor-neutral draft these extensions build on; prefer it if you want UI-bearing MCP apps that are not ChatGPT-specific.
- anthropics/skills - the Claude-side counterpart for agent-skill packaging conventions, useful as the comparison point for how each platform consumes SKILL.md.
Reviews stay honest because nobody pays us to publish them. If this one saved you time, throw a coin.
Tip the reviewer- reviewed by
- GearScope
- tested
- 2026-09-30 · macOS (Apple Silicon)
- last verified
- 2026-09-30
- depth
- HANDS-ON
- sponsorship
- none, ever
Don't install your next skill blind.
Every week: the shortlist of skills worth installing β and the ones to skip β from 100+ hands-on tests. No spam, no affiliate links.