> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unstructured.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Unstructured Transform for Codex ChatGPT Desktop

> Learn how to install the Unstructured Transform MCP server into the ChatGPT desktop app. You can then drag and drop your files and have Transform start producing partitioned, enriched, chunked, and embedded data based on your files in minutes.

## Requirements

Already set up Transform for the [Codex CLI](/transform/get-started/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](#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](https://chatgpt.com/) and click **Log in**. [Sign up for ChatGPT](https://www.chatgpt.com/signup).

* The ChatGPT desktop app, which includes Codex, installed on your local machine (macOS or Windows). [Install the ChatGPT desktop app](https://chatgpt.com/codex/). If you already have the app, or the older, standalone Codex Desktop app, [update to the latest version](https://chatgpt.com/codex/) 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:

<Tabs>
  <Tab title="Ask Codex">
    Ask Codex to install the Transform MCP server for you:

    ```text theme={null}
    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.
  </Tab>

  <Tab title="Terminal command">
    In your terminal, run the following command:

    ```bash theme={null}
    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:

    ```bash theme={null}
    codex mcp get unstructured-transform
    ```

    You should see output similar to the following:

    ```text theme={null}
    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.
  </Tab>

  <Tab title="ChatGPT desktop app">
    1. 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.

    2. Click your user icon, then **Settings**.

    3. On the sidebar, under **Integrations**, click **Plugins**.

    4. On the **Plugins** page, click the **MCPs** tab.

    5. Click **Add server**.

    6. For **Name**, enter `unstructured-transform`

    7. For **Type**, select **Streamable HTTP**.

       Don't see **Streamable HTTP** as an option? See [this Troubleshooting entry](#streamable-http-not-available).

    8. For **URL**, enter `https://mcp.transform.unstructured.io`

    9. Click **Save**.

    10. 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.

    11. Restart the ChatGPT desktop app.

    12. 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.
  </Tab>
</Tabs>

## Parse your source files

Parsing requests have the following limits:

* Each file must be of a [supported file type](/transform/supported-file-types).
* 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.

1. 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.
2. In the **Do anything** box, enter the following prompt:

   ```text theme={null}
   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:

```text theme={null}
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](/transform/sde).

## Troubleshooting

<Accordion title="Streamable HTTP isn't available as a Type option" id="streamable-http-not-available">
  **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](https://chatgpt.com/codex/). 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](https://nodejs.org/en/download).

  1. Start Codex Desktop.

  2. On the sidebar, click your user icon, and then click **Settings**.

  3. On the sidebar, under **Integrations**, click **MCP servers**.

  4. Click **Add server**.

  5. For **Name**, enter `unstructured-transform`

  6. Leave **STDIO** selected.

  7. For **Command to launch**, enter `npx`

  8. For **Arguments**, enter the following arguments, one at a time, clicking **Add argument** to add the next argument in sequence:

     a. `-y`<br />
     b. `mcp-remote`<br />
     c. `https://mcp.transform.unstructured.io`<br />

  9. Leave all of the other settings untouched, and then click **Save**.

  10. Stop Codex Desktop.

  11. In your terminal, authenticate with the Transform MCP server:

      ```bash theme={null}
      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.

  12. After you authenticate, back in your terminal, press `Ctrl + C` to exit and return to your terminal prompt.

  13. Restart Codex Desktop.

  14. The Transform MCP server is ready for you to start using. Go to [parse your source files](#parse-your-source-files) to continue.
</Accordion>

<Accordion title="Transform requires authentication again" id="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:

  1. Switch to Codex using the top-left switcher.
  2. Click your user icon, and then click **Settings**.
  3. On the sidebar, under **Integrations**, click **Plugins**.
  4. Click the **MCPs** tab.
  5. Find `unstructured-transform` in the **Servers** list, and then click **Authenticate**.
  6. 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.
  7. 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:

  ```bash theme={null}
  codex mcp login unstructured-transform
  ```

  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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](#transform-requires-authentication-again) above, then retry the tool call.
</Accordion>

<Accordion title="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](https://nodejs.org/en/download) or update to a current version, then rerun the command.
</Accordion>

<Accordion title="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](/transform/get-started/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`.
</Accordion>

<Accordion title="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.
</Accordion>

## Next steps

* [Control Transform file parsing output](/transform/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](/transform/sde): Control how the Unstructured Transform MCP server extracts and formats structured data from your files.
* [Control Transform generated sample code](/transform/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](/support/request).