# openai/mcp-extensions architecture

> Architecture diagram of the GitHub repository openai/mcp-extensions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/mcp-extensions
- Repository: https://github.com/openai/mcp-extensions

## Overview

OpenAI MCP Extensions is a pair of TypeScript and Python SDKs that add ChatGPT-specific app, resource, mention, settings, and form capabilities to MCP servers; Bits & Bolts is the example CAD plugin exercising those capabilities. The user-facing flow starts in ChatGPT (sidebar, file, composer, or form), reaches an MCP app or server extension, and returns a rendered view, resource result, or validated submission. The graph retains the demo’s catalog, tool registration, model viewing, and preview generation. Edges are limited to README statements and source relationships visible in excerpts or the SOURCE INDEX; unsampled runtime wiring is omitted.

Main entry points: [`typescript/src/server/index.ts`](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/index.ts) (Server API exports), [`plugins/bits-and-bolts/src/server/register.ts`](https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/register.ts) (CAD tool registration), [`typescript/src/shared/strings.ts`](https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/strings.ts) (String validation), [`python/src/openai_mcp_extensions/extensions.py`](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/extensions.py) (Python extensions API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ts["TypeScript SDK"]
  node_ts_server["Server extensions<br/>[extensions.ts]"]
  node_ts_forms["Form schemas<br/>[schema.ts]"]
  node_ts_fields["Form fields<br/>[fields.ts]"]
  node_ts_filepicker["File picker<br/>[file-picker.ts]"]
  node_ts_elicitation["Form elicitation<br/>[elicitation.ts]"]
  node_ts_mentions["Composer mentions<br/>[mentions.ts]"]
  node_ts_settings["Settings tools<br/>[settings.ts]"]
  node_ts_resources["Resource tools<br/>[resources.ts]"]
  node_ts_ui["UI metadata<br/>[ui.ts]"]
  node_ts_server_entry["Server API exports<br/>[index.ts]"]
  node_ts_app_entry["App API exports<br/>[index.ts]"]
  node_ts_app_extensions["App extensions<br/>[extensions.ts]"]
  node_ts_app_files["File handlers<br/>[files.ts]"]
  node_ts_app_deeplink["Sidebar entrypoints<br/>[deep-link.ts]"]
  node_ts_app_resources["App resources<br/>[resources.ts]"]
  node_ts_app_transport["MCP transport<br/>[transport.ts]"]
  node_ts_shared_resources["Shared resource metadata<br/>[resources.ts]"]
  node_ts_file_contract["File entrypoint contract<br/>[file-entrypoint.ts]"]
  node_ts_strings["String validation<br/>[strings.ts]"]
end

subgraph group_py["Python SDK"]
  node_py_api["Python extensions API<br/>[extensions.py]"]
  node_py_settings["Settings<br/>[settings.py]"]
  node_py_mentions["Mentions<br/>[mentions.py]"]
  node_py_resources["Resources<br/>[resources.py]"]
  node_py_ui["UI metadata<br/>[ui.py]"]
  node_py_forms["Form elicitation<br/>[_elicitation.py]"]
  node_py_form_schema["Form schemas<br/>[_schema.py]"]
  node_py_picker["Resource picker"]
  node_py_models["Shared models<br/>[_models.py]"]
  node_py_protocol["Form protocol<br/>[__init__.py]"]
end

subgraph group_demo["Bits &amp; Bolts Plugin"]
  node_demo_server["CAD tool registration<br/>[register.ts]"]
  node_demo_catalog[("Parts catalog<br/>[catalog.ts]")]
  node_demo_forms["CAD forms<br/>[forms.ts]"]
  node_demo_store["Catalog storage<br/>[store.ts]"]
end

subgraph group_app["MCP App Runtime"]
end

node_chatgpt(("ChatGPT user"))

node_chatgpt -->|"opens sidebar app"| node_ts_app_deeplink
node_chatgpt -->|"opens supported file"| node_ts_app_files
node_chatgpt -->|"searches resources"| node_ts_mentions
node_chatgpt -->|"submits form"| node_ts_elicitation
node_ts_server_entry -->|"exports"| node_ts_server
node_ts_server -->|"uses"| node_ts_elicitation
node_ts_server -->|"uses"| node_ts_mentions
node_ts_server -->|"uses"| node_ts_settings
node_ts_server_entry -->|"exports"| node_ts_settings
node_ts_server_entry -->|"exports"| node_ts_mentions
node_ts_server_entry -->|"exports"| node_ts_elicitation
node_ts_server_entry -->|"exports"| node_ts_forms
node_ts_server_entry -->|"exports"| node_ts_fields
node_ts_server_entry -->|"exports"| node_ts_filepicker
node_ts_server_entry -->|"exports"| node_ts_resources
node_ts_server_entry -->|"exports"| node_ts_ui
node_ts_elicitation -->|"uses schema"| node_ts_forms
node_ts_forms -->|"uses fields"| node_ts_fields
node_ts_forms -->|"uses picker"| node_ts_filepicker
node_ts_filepicker -->|"uses field shapes"| node_ts_fields
node_ts_settings -->|"validates names"| node_ts_strings
node_ts_mentions -->|"uses validation"| node_ts_strings
node_ts_ui -->|"uses validation"| node_ts_strings
node_ts_file_contract -->|"uses validation"| node_ts_strings
node_ts_app_resources -->|"uses metadata"| node_ts_shared_resources
node_ts_app_resources -->|"uses validation"| node_ts_strings
node_ts_app_entry -->|"exports"| node_ts_app_extensions
node_ts_app_entry -->|"exports"| node_ts_app_files
node_ts_app_entry -->|"exports"| node_ts_app_resources
node_py_api -->|"exposes"| node_py_settings
node_py_api -->|"exposes"| node_py_mentions
node_py_api -->|"exposes"| node_py_resources
node_py_api -->|"exposes"| node_py_ui
node_py_mentions -->|"uses models"| node_py_models
node_py_settings -->|"uses models"| node_py_models
node_py_ui -->|"uses models"| node_py_models
node_py_forms -->|"uses schema"| node_py_form_schema
node_py_forms -->|"uses protocol"| node_py_protocol
node_py_form_schema -->|"uses protocol"| node_py_protocol
node_demo_server -->|"registers"| node_demo_forms
node_demo_server -->|"uses store"| node_demo_store
node_demo_server -.->|"loads catalog"| node_demo_catalog
node_demo_server -->|"uses transport"| node_ts_app_transport
node_demo_server -.->|"serves part data"| node_demo_catalog
node_demo_store -.->|"stores catalog data"| node_demo_catalog
node_demo_server -->|"registers CAD tools"| node_demo_server

click node_ts_server "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/extensions.ts"
click node_ts_forms "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/schema.ts"
click node_ts_fields "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/fields.ts"
click node_ts_filepicker "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/file-picker.ts"
click node_ts_elicitation "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/elicitation.ts"
click node_ts_mentions "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/mentions.ts"
click node_ts_settings "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/settings.ts"
click node_ts_resources "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/resources.ts"
click node_ts_ui "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/ui.ts"
click node_ts_server_entry "https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/index.ts"
click node_ts_app_entry "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/index.ts"
click node_ts_app_extensions "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/extensions.ts"
click node_ts_app_files "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/files.ts"
click node_ts_app_deeplink "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/deep-link.ts"
click node_ts_app_resources "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/resources.ts"
click node_ts_app_transport "https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/transport.ts"
click node_ts_shared_resources "https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/resources.ts"
click node_ts_file_contract "https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/file-entrypoint.ts"
click node_ts_strings "https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/strings.ts"
click node_py_api "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/extensions.py"
click node_py_settings "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/settings.py"
click node_py_mentions "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/mentions.py"
click node_py_resources "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/resources.py"
click node_py_ui "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/ui.py"
click node_py_forms "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_elicitation.py"
click node_py_form_schema "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_schema.py"
click node_py_picker "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_resource_picker.py"
click node_py_models "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/_models.py"
click node_py_protocol "https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_form_protocol/__init__.py"
click node_demo_server "https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/register.ts"
click node_demo_catalog "https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/catalog.ts"
click node_demo_forms "https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/forms.ts"
click node_demo_store "https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/store.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ts_server,node_ts_forms,node_ts_fields,node_ts_filepicker,node_ts_elicitation,node_ts_mentions,node_ts_settings,node_ts_resources,node_ts_ui,node_ts_server_entry,node_ts_app_entry,node_ts_app_extensions,node_ts_app_files,node_ts_app_deeplink,node_ts_app_resources,node_ts_app_transport,node_ts_shared_resources,node_ts_file_contract,node_ts_strings,node_chatgpt toneBlue
class node_py_api,node_py_settings,node_py_mentions,node_py_resources,node_py_ui,node_py_forms,node_py_form_schema,node_py_picker,node_py_models,node_py_protocol toneAmber
class node_demo_server,node_demo_catalog,node_demo_forms,node_demo_store toneMint
```

## Components

### TypeScript SDK

- [Server extensions](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/extensions.ts): `typescript/src/server/extensions.ts`
- [Form schemas](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/schema.ts): `typescript/src/server/forms/schema.ts`
- [Form fields](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/fields.ts): `typescript/src/server/forms/fields.ts`
- [File picker](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/file-picker.ts): `typescript/src/server/forms/file-picker.ts`
- [Form elicitation](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/forms/elicitation.ts): `typescript/src/server/forms/elicitation.ts`
- [Composer mentions](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/mentions.ts): `typescript/src/server/mentions.ts`
- [Settings tools](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/settings.ts): `typescript/src/server/settings.ts`
- [Resource tools](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/resources.ts): `typescript/src/server/resources.ts`
- [UI metadata](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/ui.ts): `typescript/src/server/ui.ts`
- [Server API exports](https://github.com/openai/mcp-extensions/blob/main/typescript/src/server/index.ts): `typescript/src/server/index.ts`
- [App API exports](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/index.ts): `typescript/src/app/index.ts`
- [App extensions](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/extensions.ts): `typescript/src/app/extensions.ts`
- [File handlers](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/files.ts): `typescript/src/app/files.ts`
- [Sidebar entrypoints](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/deep-link.ts): `typescript/src/app/deep-link.ts`
- [App resources](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/resources.ts): `typescript/src/app/resources.ts`
- [MCP transport](https://github.com/openai/mcp-extensions/blob/main/typescript/src/app/transport.ts): `typescript/src/app/transport.ts`
- [Shared resource metadata](https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/resources.ts): `typescript/src/shared/resources.ts`
- [File entrypoint contract](https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/file-entrypoint.ts): `typescript/src/shared/file-entrypoint.ts`
- [String validation](https://github.com/openai/mcp-extensions/blob/main/typescript/src/shared/strings.ts): `typescript/src/shared/strings.ts`

### Python SDK

- [Python extensions API](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/extensions.py): `python/src/openai_mcp_extensions/extensions.py`
- [Settings](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/settings.py): `python/src/openai_mcp_extensions/settings.py`
- [Mentions](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/mentions.py): `python/src/openai_mcp_extensions/mentions.py`
- [Resources](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/resources.py): `python/src/openai_mcp_extensions/resources.py`
- [UI metadata](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/ui.py): `python/src/openai_mcp_extensions/ui.py`
- [Form elicitation](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_elicitation.py): `python/src/openai_mcp_extensions/form/_elicitation.py`
- [Form schemas](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_schema.py): `python/src/openai_mcp_extensions/form/_schema.py`
- [Resource picker](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/form/_resource_picker.py): `python/src/openai_mcp_extensions/form/_resource_picker.py`
- [Shared models](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_extensions/_models.py): `python/src/openai_mcp_extensions/_models.py`
- [Form protocol](https://github.com/openai/mcp-extensions/blob/main/python/src/openai_mcp_form_protocol/__init__.py): `python/src/openai_mcp_form_protocol/__init__.py`

### Bits & Bolts Plugin

- [CAD tool registration](https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/register.ts): `plugins/bits-and-bolts/src/server/register.ts`
- [Parts catalog](https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/catalog.ts): `plugins/bits-and-bolts/src/server/catalog.ts`
- [CAD forms](https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/forms.ts): `plugins/bits-and-bolts/src/server/forms.ts`
- [Catalog storage](https://github.com/openai/mcp-extensions/blob/main/plugins/bits-and-bolts/src/server/store.ts): `plugins/bits-and-bolts/src/server/store.ts`

### Other components

- **ChatGPT user**

## Connections

- ChatGPT user → Sidebar entrypoints: opens sidebar app (evidence: `README.md`)
- ChatGPT user → File handlers: opens supported file (evidence: `README.md`)
- ChatGPT user → Composer mentions: searches resources (evidence: `README.md`)
- ChatGPT user → Form elicitation: submits form (evidence: `README.md`)
- Server API exports → Server extensions: exports (evidence: `typescript/src/server/index.ts`)
- Server extensions → Form elicitation: uses (evidence: `typescript/src/server/extensions.ts`)
- Server extensions → Composer mentions: uses (evidence: `typescript/src/server/extensions.ts`)
- Server extensions → Settings tools: uses (evidence: `typescript/src/server/extensions.ts`)
- Server API exports → Settings tools: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → Composer mentions: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → Form elicitation: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → Form schemas: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → Form fields: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → File picker: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → Resource tools: exports (evidence: `typescript/src/server/index.ts`)
- Server API exports → UI metadata: exports (evidence: `typescript/src/server/index.ts`)
- Form elicitation → Form schemas: uses schema (evidence: `typescript/src/server/forms/elicitation.ts`)
- Form schemas → Form fields: uses fields (evidence: `typescript/src/server/forms/schema.ts`)
- Form schemas → File picker: uses picker (evidence: `typescript/src/server/forms/schema.ts`)
- File picker → Form fields: uses field shapes (evidence: `typescript/src/server/forms/file-picker.ts`)
- Settings tools → String validation: validates names (evidence: `typescript/src/server/settings.ts`)
- Composer mentions → String validation: uses validation (evidence: `typescript/src/server/mentions.ts`)
- UI metadata → String validation: uses validation (evidence: `typescript/src/server/ui.ts`)
- File entrypoint contract → String validation: uses validation (evidence: `typescript/src/shared/file-entrypoint.ts`)
- App resources → Shared resource metadata: uses metadata (evidence: `typescript/src/app/resources.ts`)
- App resources → String validation: uses validation (evidence: `typescript/src/app/resources.ts`)
- App API exports → App extensions: exports
- App API exports → File handlers: exports
- App API exports → App resources: exports
- Python extensions API → Settings: exposes (evidence: `python/src/openai_mcp_extensions/settings.py`)
- Python extensions API → Mentions: exposes (evidence: `python/src/openai_mcp_extensions/mentions.py`)
- Python extensions API → Resources: exposes
- Python extensions API → UI metadata: exposes (evidence: `python/src/openai_mcp_extensions/ui.py`)
- Mentions → Shared models: uses models (evidence: `python/src/openai_mcp_extensions/mentions.py`)
- Settings → Shared models: uses models (evidence: `python/src/openai_mcp_extensions/settings.py`)
- UI metadata → Shared models: uses models (evidence: `python/src/openai_mcp_extensions/ui.py`)
- Form elicitation → Form schemas: uses schema (evidence: `python/src/openai_mcp_extensions/form/_elicitation.py`)
- Form elicitation → Form protocol: uses protocol (evidence: `python/src/openai_mcp_extensions/form/_elicitation.py`)
- Form schemas → Form protocol: uses protocol (evidence: `python/src/openai_mcp_extensions/form/_schema.py`)
- CAD tool registration → CAD forms: registers (evidence: `plugins/bits-and-bolts/src/server/register.ts`)
- CAD tool registration → Catalog storage: uses store (evidence: `plugins/bits-and-bolts/src/server/register.ts`)
- CAD tool registration → Parts catalog: loads catalog
- CAD tool registration → MCP transport: uses transport
- CAD tool registration → Parts catalog: serves part data
- Catalog storage → Parts catalog: stores catalog data
- CAD tool registration → CAD tool registration: registers CAD tools (evidence: `plugins/bits-and-bolts/src/server/register.ts`)