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

> Learn how to connect the Unstructured Transform MCP server to Mastra agents. Your agents can then point to your files and have Transform start producing partitioned, enriched, chunked, and embedded data based on your files in minutes.

Unlike end-user AI tools that add the Transform MCP server through a settings screen, [Mastra](https://mastra.ai)
connects to it *from code*. The [`@mastra/mcp`](https://www.npmjs.com/package/@mastra/mcp) package loads the Transform
MCP server's tools as native Mastra tools, which you can then hand to any Mastra agent. Because Transform is a hosted
*remote* MCP server, there is nothing to install or run locally: you point the client at the server URL and
authenticate with your Unstructured Transform API key.

## Requirements

You will need:

* Node.js 22.13.0 or later on your local development machine. To check, in your terminal, run `node -v` or
  `node --version`. [Install Node.js](https://nodejs.org/en/download).
* An Unstructured API key, which the Transform MCP server uses as a bearer token. [Get an API key](/transform/code#get-your-unstructured-api-key-and-url).
* A chat model provider and its API key for the agent's underlying model. For example, an Anthropic or OpenAI key.
  This topic uses an Anthropic key.

## Install the packages

In your terminal, install `@mastra/mcp` along with Mastra core and a model provider (here, `@ai-sdk/anthropic`):

```bash theme={null}
npm install @mastra/mcp @mastra/core @ai-sdk/anthropic
```

Mastra uses ES modules. Make sure your project's `package.json` has `"type": "module"` set.

## Connect to the Transform MCP server

The Transform MCP server speaks the streamable HTTP transport and authenticates with your Unstructured Transform API key
sent as a bearer token. Store your keys in environment variables rather than hard-coding them. Set your Transform API key, and the
API key for your model provider (here, Anthropic):

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

Use `MCPClient` to load the Transform tools. Set the server `url` to the root endpoint
`https://mcp.transform.unstructured.io/`, and pass your API key as an `Authorization` header through `requestInit`:

```typescript theme={null}
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    unstructuredTransform: {
      url: new URL("https://mcp.transform.unstructured.io/"),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.UNSTRUCTURED_API_KEY}`,
        },
      },
    },
  },
});

// Load the Transform tools as native Mastra tools.
const tools = await mcp.listTools();
```

Mastra namespaces the loaded tools by the server key you chose, so the four Transform tools arrive as
`unstructuredTransform_transform_files`, `unstructuredTransform_check_transform_status`,
`unstructuredTransform_get_transform_results`, and `unstructuredTransform_request_file_upload_url`.

### Use the tools in a Mastra agent

After you load the tools, pass them to an agent. The following example builds a Mastra agent that drives the full
Transform job lifecycle for a file reachable at a URL:

```typescript theme={null}
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";

const mcp = new MCPClient({
  servers: {
    unstructuredTransform: {
      url: new URL("https://mcp.transform.unstructured.io/"),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.UNSTRUCTURED_API_KEY}`,
        },
      },
    },
  },
});

const agent = new Agent({
  id: "transform-agent",
  name: "transform-agent",
  instructions:
    "You process documents using the Unstructured Transform tools. Submit the file, " +
    "poll status until the job is COMPLETED, then fetch and summarize the results.",
  model: anthropic("claude-sonnet-4-6"),
  tools: await mcp.listTools(),
});

const fileUrl = "https://example.com/report.pdf";

const response = await agent.generate(
  `Use the Unstructured Transform tools to parse the file at ${fileUrl}. ` +
    `Report the job_id, the final status, and the element_count and character_count from the results.`,
  { maxSteps: 50 },
);

console.log(response.text);

await mcp.disconnect();
```

The agent decides when to call each Transform tool: it submits the file, polls for status, and fetches the results.
Because an agent cannot pause between tool calls, it may call the status tool many times in quick succession while the
job runs. The server caches each status snapshot, so this is harmless, but set `maxSteps` high enough (for example, `50`)
that the agent reaches the results step before hitting the step limit.

## 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 the agent through its tool responses. Because of
this, your agent should notify you whenever it encounters a file that exceeds 50 MB in size, and it 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. You
can reinforce this behavior in your agent's system prompt.

The `transform_files` tool accepts each input as a URL. The simplest path, shown above, is to pass an `https://` URL that
Transform can fetch directly (for example, a public URL or a pre-signed storage URL).

To parse a *local* file, upload it first. The `request_file_upload_url` tool returns a signed `upload_url`, the HTTP
`method` and `headers` to use, and a `file_ref`. Send the file's bytes to `upload_url` with that method and those
headers, then pass the returned `file_ref` (a `u10d://file/...` value) to `transform_files` in place of a URL. Perform
this upload step in your own code, because a Mastra agent has no ability to read local files or make raw HTTP requests on
its own.

### Provide credentials per request

The bearer-token approach shown above loads the tools once with a single API key, which works well for scripts,
backends, and shared-service setups. If you instead need to vary the credential per request (for example, a different
end user's key on each call), build a fresh `MCPClient` for that request and pass its toolsets to the agent's
`generate` call rather than binding the tools at agent construction:

```typescript theme={null}
const requestScopedMcp = new MCPClient({
  // Give each request-scoped client a unique id. Building two MCPClients with an
  // identical configuration throws, so derive the id from the request.
  id: `unstructured-transform-${requestId}`,
  servers: {
    unstructuredTransform: {
      url: new URL("https://mcp.transform.unstructured.io/"),
      requestInit: {
        headers: {
          Authorization: `Bearer ${perRequestApiKey}`,
        },
      },
    },
  },
});

try {
  const response = await agent.generate(prompt, {
    toolsets: await requestScopedMcp.listToolsets(),
  });
  console.log(response.text);
} finally {
  await requestScopedMcp.disconnect();
}
```

See the [Mastra MCP documentation](https://mastra.ai/docs/mcp/overview) for more on static tools versus per-request
toolsets.

## Troubleshooting

* **`401 Unauthorized` on tool calls.** Confirm the `UNSTRUCTURED_API_KEY` environment variable is set to your Transform
  API key and that the `Authorization` header is formatted as `Bearer <your-unstructured-transform-api-key>`.
  [Get or manage your Transform API key](https://transform.unstructured.io/get-started).
* **Authentication errors from the model provider.** Confirm the model provider's API key is set. The Anthropic example
  reads `ANTHROPIC_API_KEY` from the environment.
* **`404 Not Found` when connecting.** Verify the URL is the root endpoint `https://mcp.transform.unstructured.io/`,
  including the trailing slash, and not a path such as `/mcp`.
* **`Cannot find package '@mastra/mcp'`.** Re-run `npm install @mastra/mcp @mastra/core @ai-sdk/anthropic` in the same
  project that runs your agent, and confirm `package.json` has `"type": "module"`.
* **No tools are loaded.** Check that your network allows outbound HTTPS to `mcp.transform.unstructured.io`.
* **The agent stops before returning results.** It likely hit the `maxSteps` limit while polling the job status. Raise
  `maxSteps` on the `generate` call.

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