Unstructured Transform MCP server installation for Mastra

Unlike end-user AI tools that add the Transform MCP server through a settings screen, Mastra connects to it from code. The @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.
An Unstructured API key, which the Transform MCP server uses as a bearer token. Get an API key.
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):

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):

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:

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:

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

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

For technical support, request support.

​Requirements

​Install the packages

​Connect to the Transform MCP server

​Use the tools in a Mastra agent

​Parse your source files

​Provide credentials per request

​Troubleshooting

​Next steps

​Questions? Need help?