Skip to main content
You can connect 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.
  • An Unstructured account for the OAuth sign-in, or an Unstructured API key for bearer-token authentication. Get an API key.

​
Install the Transform MCP server

You should be able to instruct Goose to install the Transform MCP server by asking Goose the following:
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.

​
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:
Then export the key in the shell that runs the Goose CLI:
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.

​
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 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:
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: 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: 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?