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

# Unstructured Transform MCP server installation for Goose

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

You can connect [Goose](https://block.github.io/goose/), Block's open-source AI agent, to the Transform MCP server. Goose extensions are MCP servers, so Goose communicates with Transform natively over the streamable HTTP transport.
Because Transform is a hosted *remote* MCP server, there is nothing to install or run locally: you point Goose at the
server URL and authenticate.

Goose supports two ways to authenticate with Transform:

* **OAuth (simplest)**: Add the extension with only the server URL. When Goose first connects to the extension, a
  browser window opens for you to sign in to Unstructured. This is a one-time sign-in. Goose stores the tokens in
  your system keychain and refreshes them automatically, so later sessions connect without the browser.
* **API key**: Send an Unstructured API key as a bearer token in a request header. Use this for headless or CI runs of
  the Goose CLI, where a browser sign-in is not practical.

## Requirements

Before you begin, you must have the following:

* Goose Desktop or the Goose CLI installed on your local development machine, with a model provider configured.
  [Install Goose](https://block.github.io/goose/docs/getting-started/installation).
* An Unstructured account for the OAuth sign-in, or an Unstructured API key for bearer-token authentication.
  [Get an API key](/transform/code#get-your-unstructured-api-key-and-url).

## Install the Transform MCP server

<Tip>
  You should be able to instruct Goose to install the Transform MCP server by asking Goose the following:

  ```text theme={null}
  Install the Unstructured Transform MCP server by using these instructions: 
  https://docs.unstructured.io/transform/install/goose.md
  ```

  If this does not work, install the Transform MCP server manually using the following steps.

  If you are able to successfully connect, skip ahead to [parse your source files](#parse-your-source-files).
</Tip>

### Goose Desktop

1. Start Goose Desktop.

2. Click the panel button in the top-left corner to open the sidebar, and then click **Extensions**.

3. Under **Extensions**, click **Add custom extension**.

4. In the **Add custom extension** dialog, enter the following details:

   * For **Extension Name**, enter `Unstructured Transform`.
   * For **Type**, select `Streamable HTTP`.
   * (Optional) For **Description**, enter a short description, such as `Turn documents into LLM-ready Markdown`.
   * For **Endpoint**, enter `https://mcp.transform.unstructured.io`.
   * For **Timeout**, enter `300`. Transforms take from about 10 seconds to several minutes, and this sets how long
     Goose waits for a tool call to complete.
   * Leave **Request Headers** empty to use OAuth. To use an API key instead, enter a header name of `Authorization`
     and a value of `Bearer <your-unstructured-api-key>`, and then click the plus button to add the header.

5. Click **Add Extension**.

6. Start a new chat. If you left the request headers empty, a browser window opens when Goose connects to the
   extension: sign in to Unstructured to finish connecting.

### Goose CLI

The CLI shares its configuration file with Goose Desktop, so an extension added in one appears in the other. You
may need to complete the OAuth sign-in once per interface.

1. In your terminal, run `goose configure`. On a brand-new install, `goose configure` walks you through model
   provider setup first; rerun it afterward to reach the extensions menu.
2. Select **Add Extension**, and then select **Remote Extension (Streamable HTTP)**.
3. For the extension name, enter `unstructured-transform`.
4. For the URI, enter `https://mcp.transform.unstructured.io`.
5. For the timeout, enter `300`.
6. For the description, enter a short description or accept the default.
7. When asked about custom headers:
   * For OAuth, answer no.
   * For API key authentication, answer yes and add a header named `Authorization` with the value `Bearer <your-unstructured-api-key>`.

Alternatively, you can edit `~/.config/goose/config.yaml` directly. The following entry uses API key authentication with the
key substituted from an environment variable at connection time, which keeps the key out of the file:

```yaml theme={null}
extensions:
  unstructured-transform:
    enabled: true
    type: streamable_http
    name: unstructured-transform
    uri: https://mcp.transform.unstructured.io
    headers:
      Authorization: Bearer ${UNSTRUCTURED_API_KEY}
    env_keys:
      - UNSTRUCTURED_API_KEY
    timeout: 300
```

Then export the key in the shell that runs the Goose CLI:

```bash theme={null}
export UNSTRUCTURED_API_KEY="<your-unstructured-api-key>"
```

<Note>
  The `env_keys` entry is required. Goose substitutes `${UNSTRUCTURED_API_KEY}` in header values only from keys it
  resolves through `env_keys`, which reads the environment variable of the Goose process. The Goose Desktop app does
  not inherit variables you export in a terminal, so for Goose Desktop either use OAuth or put the literal key in the
  header value.
</Note>

## 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 report these limits back to Goose through its tool responses. Because of
this, Goose should notify you whenever it encounters a file that exceeds 50 MB in size. Goose should also formulate
strategies to send requests that are 10 files or fewer and not cause more than 5 requests to be running at a time.

Ask Goose to transform a document:

```text theme={null}
Use the unstructured-transform tools to transform ./quarterly-report.pdf into markdown. Upload the file bytes yourself with a plain HTTP PUT to the pre-signed upload URL, without an Authorization header on that request. Then give me the element count and a preview of the output.
```

Goose drives the full job lifecycle: it requests a pre-signed upload URL, uploads the file bytes with its built-in
shell tools, starts the transform, polls until the job completes, and downloads the finished Markdown. Goose shows
the result inline by default; ask it to save the output to a file if you want the Markdown on disk.

The upload and download URLs are pre-signed and reject requests that carry an `Authorization` header. The example
prompt reminds Goose of this; if an upload fails with an authorization error, tell Goose to retry the request
without that header.

## Troubleshooting

* **No OAuth window appears.** The browser sign-in triggers when Goose connects to the extension, which happens at
  the start of a session. Start a new chat (or a new `goose session`), then complete the sign-in.
* **`401 Unauthorized` or an `invalid_token` error.** If you configured an `Authorization` header, confirm the value
  is formatted as `Bearer <your-unstructured-api-key>`. For the `${UNSTRUCTURED_API_KEY}` form, confirm the config
  entry also lists the variable under `env_keys` and that the variable is exported in the shell running the Goose
  CLI.
* **The extension fails to connect in Goose Desktop but works in the CLI.** This usually means the header references
  an environment variable that the desktop app does not inherit. Use OAuth or the literal key in Goose Desktop.
* **macOS keeps asking to allow Goose to access the keychain.** Goose stores the OAuth tokens in a keychain item
  that it reads at every session start, and macOS approves keychain access per binary. Click **Always Allow** for
  each Goose binary (the Desktop app and the CLI are separate). A Homebrew upgrade replaces the CLI binary and
  resets the approval, so expect one new prompt after upgrading.
* **`404` when connecting.** Verify the endpoint is exactly `https://mcp.transform.unstructured.io`, with no path
  appended.
* **`goose run` panics with an `index out of bounds` or `no rows returned` error.** A Homebrew-installed CLI and
  Goose Desktop at different versions can collide on the shared session database. Update the two to matching
  versions, or isolate the CLI by setting `XDG_DATA_HOME` to a separate directory before running.
* **The OAuth window signs you in to an unexpected server.** If you have more than one Transform-style extension
  configured, the sign-in can belong to a different extension. Disable the others before the first sign-in.
* **The tools stop before a long transform finishes.** Raise the extension's `timeout` value. `300` seconds covers
  most documents.

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