Get started with Unstructured Transform for Codex ChatGPT Desktop

Requirements

Already set up Transform for the Codex CLI on this machine? You may already have it here, too. To check, switch to Codex using the top-left switcher of the ChatGPT desktop app. Then in the prompt box, enter /mcp to confirm unstructured-transform is listed. If so, skip ahead to parse your source files. Otherwise, before you begin, you must have the following:

A ChatGPT plan. To see if you have a plan, go to ChatGPT and click Log in. Sign up for ChatGPT.
The ChatGPT desktop app, which includes Codex, installed on your local machine (macOS or Windows). Install the ChatGPT desktop app. If you already have the app, or the older, standalone Codex Desktop app, update to the latest version before continuing. These instructions assume the latest version, which includes Codex.

Install the Transform MCP server

To install and authenticate the Transform MCP server, use one of the following methods:

Ask Codex
Terminal command
ChatGPT desktop app

Ask Codex to install the Transform MCP server for you:

Install the Unstructured Transform MCP server by using these instructions: 
https://docs.unstructured.io/transform/get-started/codex-desktop.md

During this process, Codex will open a browser window where you sign in to Transform to complete authentication. If you do not have a Transform account, click Register and then follow the on-screen directions to finish authenticating. Once authenticated, close the browser and return to Codex.You’re ready to ask Codex to parse your source files using the Transform MCP server.

In your terminal, run the following command:

codex mcp add unstructured-transform \
  --url https://mcp.transform.unstructured.io

Codex will open a browser window where you sign in to Transform to complete authentication. If you do not have a Transform account, click Register and then follow the on-screen directions to finish authenticating. Once authenticated, restart the ChatGPT desktop app.To confirm the server is set up correctly, run:

codex mcp get unstructured-transform

You should see output similar to the following:

unstructured-transform
  enabled: true
  transport: streamable_http
  url: https://mcp.transform.unstructured.io
  bearer_token_env_var: -
  http_headers: -
  env_http_headers: -
  remove: codex mcp remove unstructured-transform

You’re ready to ask Codex to parse your source files using the Transform MCP server.

In the ChatGPT desktop app, switch to Codex using the top-left switcher. You must be in Codex mode to add an MCP server; the option isn’t available in ChatGPT mode.
Click your user icon, then Settings.
On the sidebar, under Integrations, click Plugins.
On the Plugins page, click the MCPs tab.
Click Add server.
For Name, enter unstructured-transform
For Type, select Streamable HTTP. Don’t see Streamable HTTP as an option? See this Troubleshooting entry.
For URL, enter https://mcp.transform.unstructured.io
Click Save.
On the MCP tab, next to unstructured-transform in the Servers list, click Authenticate, and then follow the on-screen directions in your browser to finish authenticating. If you do not have a Transform account, click Register and then follow the on-screen directions to finish authenticating.
Restart the ChatGPT desktop app.
Switch to Codex using the top-left switcher, and then in the prompt box, enter /mcp to confirm the server is listed.

You’re ready to ask Codex to parse your source files using the Transform MCP server.

Parse your source files

Parsing requests have the following limits:

Each file must be of a supported file type.
Each file must be 50 MB or less in size.
Each request must have 10 files or fewer.
Only 5 requests can be running at a time.

The Transform MCP server is designed to notify Codex about these limits. Because of this, Codex should notify you whenever it encounters a file that exceeds 50 MB in size. Also, Codex should formulate strategies to send requests that are 10 files or fewer and not cause more than 5 requests to be running at a time.

After you install the Transform MCP server, switch to Codex using the top-left switcher in the ChatGPT desktop app. Then select the project containing the folder that stores the files you want Transform to parse.
In the Do anything box, enter the following prompt:
Use the Unstructured Transform MCP server to parse the files in this project. Provide the results as JSON files, one JSON file per source file.
As needed, adapt the phrase in this project in the preceding prompt to indicate a more specific project folder. Also, as needed, guide Codex as to where to write Transform’s output into the project. Transform parses your input files and delivers its results to you as a set of output files, one output file per input file.

Extract structured data

If you want to pull specific fields from your files, instead of converting the files in full, ask for an extraction. To determine what structured data Transform can extract from your files, use a prompt similar to the following:

Use the Unstructured Transform MCP server to extract structured data from these files.

I don't have a schema — suggest one based on what's in the document, show it to me, and then run the extraction with it.

Your tool parses each file first, then extracts the field values from the parsed element JSON; this is because the Transform MCP extraction tools read a file’s parsed output, rather than the raw file itself. Transform returns results as JSON matching the schema, wrapped with the source filename so you can tell a batch apart. If you know the specific fields you want, include them in your prompt to guide Transform in extracting just the information that’s important to you. For more information, including prompting patterns and performance considerations, see Structured data extraction.

Troubleshooting

Streamable HTTP isn't available as a Type option

Issue: When adding an MCP server in the ChatGPT desktop app, Streamable HTTP isn’t available as a Type option.Cause: This indicates you have the older, standalone Codex Desktop app instead of the latest version of the ChatGPT desktop app.Solution: Update to the latest ChatGPT desktop app. If you cannot update, follow these steps to use the legacy STDIO bridge with mcp-remote. The older, standalone Codex Desktop app only supports local STDIO connections; mcp-remote lets it reach the Transform MCP server over HTTP. This requires Node.js. To see if it is installed, in your terminal, run node -v or node --version. Install Node.js.

Start Codex Desktop.
On the sidebar, click your user icon, and then click Settings.
On the sidebar, under Integrations, click MCP servers.
Click Add server.
For Name, enter unstructured-transform
Leave STDIO selected.
For Command to launch, enter npx
For Arguments, enter the following arguments, one at a time, clicking Add argument to add the next argument in sequence: a. -y
b. mcp-remote
c. https://mcp.transform.unstructured.io
Leave all of the other settings untouched, and then click Save.
Stop Codex Desktop.
In your terminal, authenticate with the Transform MCP server:
npx -y mcp-remote https://mcp.transform.unstructured.io
A web browser tab appears, prompting you to authenticate with Transform. If you do not have a Transform account, click Register and then follow the on-screen directions to finish authenticating.
After you authenticate, back in your terminal, press Ctrl + C to exit and return to your terminal prompt.
Restart Codex Desktop.
The Transform MCP server is ready for you to start using. Go to parse your source files to continue.

Transform requires authentication again

Issue: /mcp shows unstructured-transform as not connected, or you were never prompted to sign in.Cause: Your Transform session expired, or the server was added without completing the browser sign-in, for example, if you configured it from a terminal.Solution: The Servers list shows an Authenticate action next to unstructured-transform whenever sign-in is needed:

Switch to Codex using the top-left switcher.
Click your user icon, and then click Settings.
On the sidebar, under Integrations, click Plugins.
Click the MCPs tab.
Find unstructured-transform in the Servers list, and then click Authenticate.
Follow the on-screen directions to finish authenticating in your browser. If you do not have a Transform account, click Register to create one, and then complete authentication.
In the prompt box, enter /mcp to confirm the server is connected.

If you prefer to authenticate from a terminal, run the following command instead:

codex mcp login unstructured-transform

Server doesn't appear after adding it

Issue: You added unstructured-transform, but it doesn’t appear in /mcp or in the Codex CLI.Cause: The ChatGPT desktop app only picks up a newly added MCP server after a restart.Solution: Restart the ChatGPT desktop app. Then switch to Codex using the top-left switcher, and in the prompt box, enter /mcp to confirm the server is listed.

Tool calls fail with an authentication error

Issue: unstructured-transform shows as connected, but tool calls return a 401 or 403 error.Cause: Your Transform access token expired or was revoked, even though the connection itself still shows as active.Solution: Re-authenticate using the steps in Transform requires authentication again above, then retry the tool call.

mcp-remote fails to run

Issue: Running npx -y mcp-remote https://mcp.transform.unstructured.io does not open a browser window, or the command fails.Cause: Node.js is missing, or an outdated version is installed.Solution: Run node -v or node --version to check your Node.js version. Install Node.js or update to a current version, then rerun the command.

Codex CLI and Codex ChatGPT Desktop show different servers

Issue: A server you added in one Codex client doesn’t appear in another. Codex mode in the ChatGPT desktop app and the Codex CLI share MCP configuration on the same machine, so this is unexpected.Cause: Each client only picks up configuration changes made by another client after that client restarts.Solution: Restart the client that isn’t showing the new server, then confirm with /mcp.

Inspect the server's configuration from the terminal

Use these commands to inspect the Transform MCP server’s configuration. These commands reveal information that’s also applicable to the ChatGPT desktop app.

codex mcp list: Shows all configured MCP servers.
codex mcp get unstructured-transform: Shows the Transform MCP server’s configuration.
codex mcp get unstructured-transform --json: Shows the same configuration as JSON.
codex mcp --help: Shows all available MCP management commands.

These commands show the server’s configuration, not whether it’s actively connected. There’s no terminal command to check the live connection state. To confirm the connection, switch to Codex using the top-left switcher in the ChatGPT desktop app, and then enter /mcp in the prompt box.

Next steps

Control Transform file parsing output: Control how the Unstructured Transform MCP server instructs Transform to partition, enrich, chunk, and embed the data based on your files.
Control Transform structured data extraction: Control how the Unstructured Transform MCP server extracts and formats structured data from your files.
Control Transform generated sample code: Control how the Unstructured Transform MCP server generates sample curl or Python code that demonstrates how to use Transform to partition, enrich, chunk, and embed the data based on your files.

Questions? Need help?

For technical support, request support.

​Requirements

​Install the Transform MCP server

​Parse your source files

​Extract structured data

​Troubleshooting

​Next steps

​Questions? Need help?