> ## 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 Devin (formerly Windsurf)

> Learn how to connect the Unstructured Transform MCP server in the Devin CLI or Devin Desktop, then parse your files into partitioned, enriched, chunked, and embedded data.

<Accordion title="Have you already installed Transform in Devin?">
  The Devin CLI and Devin Desktop's Devin Local agent share the same MCP configuration, so if you already installed the Transform MCP server using one, it's already available in the other.

  **To check from the Devin CLI, run:**

  ```bash theme={null}
  devin mcp list
  ```

  If `unstructured-transform` appears in the list, skip ahead to [parse your source files](#parse-your-source-files).

  **To check from Devin Desktop:**

  <Steps>
    <Step>
      Start Devin Desktop.
    </Step>

    <Step>
      Click **Customizations** at the bottom left of the screen, and look for **unstructured-transform** listed as **Connected** under **MCPs**.
    </Step>
  </Steps>

  If **unstructured-transform** appears as **Connected**, skip ahead to [parse your source files](#parse-your-source-files).

  If **unstructured-transform** appears but is not connected, select the [Devin Desktop](#devin-desktop-install) tab under Install the Transform MCP server, and complete the **Connect and authenticate** step. Devin Desktop opens a browser window where you sign in to Transform.

  If `unstructured-transform` does not appear at all, Transform is not installed here yet. Continue with [Install the Transform MCP server](#install-the-transform-mcp-server).
</Accordion>

## Requirements

You will need:

* A Devin account. To see if you have one, [log in to your Devin account](https://app.devin.ai/auth/login). [Sign up for Devin](https://app.devin.ai/auth/signup).
* The Devin CLI or Devin Desktop installed on your local development machine.
  * [Install the Devin CLI](https://cli.devin.ai/docs)
  * [Install Devin Desktop](https://devin.ai/download)

## Install the Transform MCP server

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

<Tabs>
  <Tab title="Ask Devin">
    Ask Devin 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/devin.md
    ```

    During this process, Devin 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 Devin.

    <Check>
      You're ready to [parse your source files](#parse-your-source-files).
    </Check>
  </Tab>

  <Tab title="Devin CLI">
    <Steps>
      <Step title="Add the Transform MCP server">
        In your terminal, run this command:

        ```bash theme={null}
        devin mcp add unstructured-transform --transport http --url https://mcp.transform.unstructured.io --scope user
        ```

        `--scope user` makes the server available across all your project folders, in both the Devin CLI and Devin Desktop's Devin Local agent.
      </Step>

      <Step title="Authenticate with the Transform MCP server">
        Run:

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

        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.

        If you also use Devin Desktop, restart it, then select **Devin Local** as the agent for a new session to confirm the server is available there too.
      </Step>
    </Steps>

    <Check>
      You're ready to [parse your source files](#parse-your-source-files).
    </Check>
  </Tab>

  <Tab title="Devin Desktop" id="devin-desktop-install">
    These steps configure Devin Desktop to use the Devin Local agent, not Cascade (Devin Desktop's other agent). The Devin Local agent shares the Devin CLI's agent harness, so it uses the same MCP configuration and [tool-approval behavior](#approve-transform-tool-calls-automatically). [Learn more about the Devin Local agent](https://docs.devin.ai/desktop/devin-local) in the Devin documentation.

    <Steps>
      <Step title="Open Devin Settings">
        Start Devin Desktop. On the menu bar, click **Devin**, then **Preferences**, then **Devin Settings**. On the **Devin Settings** sidebar, under **Devin Local**, click **Configuration**.
      </Step>

      <Step title="Open Devin Customizations">
        Next to **MCP servers**, click **Open Devin MCP marketplace**. This opens the **Devin Customizations** tab.
      </Step>

      <Step title="Add a custom MCP server">
        On the **Devin Customizations** tab, click **Add custom MCP**.

        Devin Desktop opens the `mcp_config.json` settings file in a new editor tab. This is the same user-scope file the Devin CLI uses.
      </Step>

      <Step title="Add the Transform MCP server entry">
        Add the following entry to the `mcpServers` object, and then save and close the `mcp_config.json` file:

        ```json theme={null}
        {
          "mcpServers": {
            "unstructured-transform": {
              "url": "https://mcp.transform.unstructured.io",
              "transport": "http"
            }
          }
        }
        ```
      </Step>

      <Step title="Connect and authenticate">
        Back in the **Devin Customizations** tab, in the **Installed** area, **unstructured-transform** shows as **not connected**. Click it, and on the next page, click **Connect**.

        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.
      </Step>
    </Steps>

    <Check>
      You're ready to [parse your source files](#parse-your-source-files).
    </Check>
  </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 Devin about these limits. Because of this, Devin should notify you whenever it encounters a file that exceeds 50 MB in size. Also, Devin 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.

<Tabs>
  <Tab title="Devin CLI">
    <Steps>
      <Step title="Switch to your project folder">
        After you install the Transform MCP server, from your terminal, switch to the folder that stores the files you want Transform to parse.
      </Step>

      <Step title="Start a Devin CLI session">
        Start a Devin CLI session by running the `devin` command.
      </Step>

      <Step title="Enter the parse prompt">
        Enter this 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 the Devin CLI 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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Devin Desktop">
    <Steps>
      <Step title="Open your project folder">
        After you install the Transform MCP server, open the folder that stores the files you want Transform to parse. From the main menu, click **File**, then **Open Folder**.

        <Note>
          If a **Restricted Mode** banner appears at the top of the screen, click **Manage**. Next, in the **Workspace Trust** dialog, click **Trust** to enable full access to the folder. Then close the **Workspace Trust** dialog.
        </Note>
      </Step>

      <Step title="Start a new session">
        In the **Agent** sidebar (from the main menu, click **View**, then **Appearance**, then **Agent Sidebar**), click **New Session**. If **Devin Local** does not appear in the agent picker, see [Devin Local doesn't appear in the agent picker](#devin-local-doesnt-appear-in-the-agent-picker) in Troubleshooting.
      </Step>

      <Step title="Enter the parse prompt">
        In the prompt 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 Devin Desktop 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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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).

## Approve Transform tool calls automatically

The Devin CLI and Devin Desktop's Devin Local agent ask for approval each time they call a Transform MCP server tool that you have not already approved. Devin lets you pre-approve specific tools so it stops prompting for them individually.

Transform's MCP tools follow Devin's standard naming pattern: `mcp__unstructured-transform__<tool-name>`. For example, to pre-approve every Transform tool, add this `permissions` object to your Devin config file. If `permissions` already exists, add the `allow` entry to its existing list:

* For macOS and Linux: `~/.config/devin/config.json`
* For Windows: `%APPDATA%\devin\config.json`

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__unstructured-transform__*"
    ]
  }
}
```

This example is confirmed as of Devin CLI v3000.4.16. For the most current details, see Devin's [permissions reference](https://docs.devin.ai/cli/reference/permissions).

## Troubleshooting

<Accordion title="(Both) MCP configuration file locations" id="mcp-configuration-file-locations">
  The Devin CLI writes to the shared, user-scope configuration file only when you use `--scope user`, as in our install steps. Without it, the CLI defaults to a project-only file instead. Devin Desktop's Devin Local agent always writes to this same file. Both use this location:

  * For macOS and Linux: `~/.config/devin/mcp_config.json`
  * For Windows: `%APPDATA%\devin\mcp_config.json`

  Other `--scope` values place this file elsewhere:

  * Default (no `--scope` flag): `.devin/mcp_config.local.json` (project-only, gitignored)
  * `--scope project`: `.devin/mcp_config.json` (shared via git)

  This reflects the file scheme introduced in Devin CLI v3000.3.22 (released July 29, 2026). For the most current details, see Devin's [changelog](https://docs.devin.ai/cli/changelog/stable), [MCP configuration reference](https://docs.devin.ai/cli/extensibility/mcp/configuration#via-config-file), and [configuration scope reference](https://docs.devin.ai/cli/reference/configuration/global-vs-local#what's-available-at-each-level).
</Accordion>

<Accordion title="(CLI) Inspect the server's configuration from the terminal">
  Use these commands to inspect the Transform MCP server's configuration. This is also what Devin Desktop's Devin Local agent uses. See [MCP configuration file locations](#mcp-configuration-file-locations) above.

  * `devin mcp list`: List all configured MCP servers.
  * `devin mcp get unstructured-transform`: Get details for a specific MCP server.
  * `devin mcp help`: Show all available MCP management commands.

  These commands show the server's configuration, not whether it's actively connected. To confirm the connection, check the Customizations panel in Devin Desktop's Devin Local agent.
</Accordion>

<Accordion title="(CLI) Transform requires authentication again">
  **Issue**: `devin mcp list` or `devin mcp get unstructured-transform` shows the server configured, but tool calls fail with an authentication error, or you were never prompted to sign in.

  **Cause**: Your Transform session expired, or the server was added without completing the browser sign-in step.

  **Solution**: Run:

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

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

<Accordion title="(Desktop) unstructured-transform doesn't appear in the Customizations panel or does not show as Connected">
  **Issue**: **unstructured-transform** does not appear in the **Customizations** panel at the bottom left of the screen, or does not show as **Connected**.

  **Cause**: The Transform MCP server is not connected.

  **Solution**: Click **Customizations** and verify that **unstructured-transform** is listed as **Connected** under **MCPs** for the **Devin Local** agent. If it is not connected, return to the [Devin Desktop](#devin-desktop-install) tab under Install the Transform MCP server and reconnect.
</Accordion>

<Accordion title="(Desktop) Devin cannot run tasks or access files in the project folder">
  **Issue**: Devin cannot run tasks or access files after opening a project folder.

  **Cause**: The folder is in Restricted Mode, which disables tasks, debugging, workspace settings, and extensions.

  **Solution**: Switch to **Editor mode** by clicking the **Editor** button in the top left corner. Check for a **Restricted Mode** banner at the top of the screen. If it appears, click **Manage**, then click **Trust** in the **Workspace Trust** dialog, and then close the dialog. If the banner does not appear, open the Command Palette (from the main menu, click **View**, then **Command Palette**), type **Manage Workspace Trust**, and select it to open the **Workspace Trust** dialog directly.
</Accordion>

<Accordion title="(Desktop) Devin Local doesn't appear in the agent picker" id="devin-local-doesnt-appear-in-the-agent-picker">
  **Issue**: **Devin Local** does not appear as an option in the agent picker when starting a new session.

  **Cause**: The ACP (Agent Client Protocol) setting that enables **Devin Local** is turned off.

  **Solution**:

  <Steps>
    <Step>
      Open the Command Palette (from the main menu, click **View**, then **Command Palette**).
    </Step>

    <Step>
      Type `>Open Devin User Settings` and select it.
    </Step>

    <Step>
      In the **Devin Settings** editor tab, on the sidebar, click **Agents**.
    </Step>

    <Step>
      In the **Agents** section, turn on the switch labeled **Enable ACP**, if it is not already turned on.
    </Step>

    <Step>
      If **Devin Local** does not show as **Enabled**, click the **Enable** button.
    </Step>

    <Step>
      Go back to the agent picker. **Devin Local** should now appear.
    </Step>
  </Steps>
</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).