Unstructured Transform MCP server installation for CrewAI

​

Requirements

• Python 3.12 to 3.13 on your local development machine. Install Python.
  • CrewAI may support older Python versions, but mcpadapt, the MCP adapter layer used internally by crewai-tools, requires Python 3.12 or later.
  • The supported Python version range may have changed since this page was last published. For the current supported range, see Getting started with the installation in the CrewAI documentation.
• An Unstructured API key, which the Transform MCP server uses as a bearer token. To get one, see Get your API key and API URL.
• An LLM provider and its API key (for example, an Anthropic or OpenAI key) for the agent’s underlying model. See LLMs in the CrewAI documentation for supported providers.
• A file to parse. You will provide the path to your file at the top of the example script.

​

Install the packages

pip install -U "crewai[<LLM-provider>]>=0.108.0" "crewai-tools[mcp]>=0.76.0" "mcp>=1.10.1,<2.0.0" httpx

• Anthropic:
  pip install -U "crewai[anthropic]>=0.108.0" "crewai-tools[mcp]>=0.76.0" "mcp>=1.10.1,<2.0.0" httpx
  
• OpenAI:
  pip install -U "crewai[openai]>=0.108.0" "crewai-tools[mcp]>=0.76.0" "mcp>=1.10.1,<2.0.0" httpx
  

crewai --version

​

Connect to the Transform MCP server

export UNSTRUCTURED_API_KEY="<your-unstructured-api-key>"

import os

from crewai_tools import MCPServerAdapter

with MCPServerAdapter(
    {
        "url": "https://mcp.transform.unstructured.io",
        "transport": "streamable-http",
        "headers": {"Authorization": f"Bearer {os.environ['UNSTRUCTURED_API_KEY']}"},
    },
    connect_timeout=60,
) as mcp_tools:
    # mcp_tools is a list of native CrewAI tools loaded from the Transform server.
    print([t.name for t in mcp_tools])

​

Use the tools in a CrewAI agent

• Defines two local tools the agent can call: one to upload a local file to a pre-signed URL, and one to download parsed results from a pre-signed URL.
• Creates a CrewAI agent with access to both local tools and all the Transform MCP tools. The agent uses an LLM to decide when to call each tool.
• Gives the agent a task: parse a file and return a short summary. The task description walks the agent through the full sequence: request an upload URL, upload the file, start the job, poll for status, download the results.
• Runs the crew, which kicks off the agent and prints the result.

​

Set your API key environment variables

• Your Unstructured API key as UNSTRUCTURED_API_KEY. If you followed the Connect to the Transform MCP server section, this is already set. To confirm:
  echo $UNSTRUCTURED_API_KEY
  
• Your LLM provider API key as the appropriate environment variable.
  • Anthropic example:
    export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
    
  • OpenAI example:
    export OPENAI_API_KEY="<your-openai-api-key>"
    
  For the correct environment variable name for your provider, see LLMs in the CrewAI documentation.

echo $ANTHROPIC_API_KEY

​

Update the script variables

1. Set FILE_PATH to the path of the file you want the Transform MCP server to parse.
2. Set LLM_MODEL to the model string for your LLM provider. The example defaults to "anthropic/claude-sonnet-4-6".

​

Run the script

import mimetypes
import os
from pathlib import Path

FILE_PATH = "./report.pdf"  # Replace with the path to your file.
LLM_MODEL = "anthropic/claude-sonnet-4-6"  # Format: provider/model-name. See https://docs.crewai.com/concepts/llms

import httpx
from crewai import LLM, Agent, Crew, Task
from crewai.tools import tool
from crewai_tools import MCPServerAdapter


@tool("Upload file to pre-signed URL")
def upload_file(local_path: str, upload_url: str) -> str:
    """Upload a local file's bytes to a pre-signed upload URL."""
    path = Path(local_path)
    content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
    data = path.read_bytes()
    response = httpx.put(
        upload_url,
        content=data,
        headers={"Content-Type": content_type},
        timeout=60,
    )
    response.raise_for_status()
    return f"Uploaded {len(data)} bytes."


@tool("Download results from pre-signed URL")
def download_results(download_url: str) -> str:
    """Fetch parsed results from a pre-signed download URL."""
    response = httpx.get(download_url, timeout=60)
    response.raise_for_status()
    return response.text


def main() -> None:
    with MCPServerAdapter(
        {
            "url": "https://mcp.transform.unstructured.io",
            "transport": "streamable-http",
            "headers": {"Authorization": f"Bearer {os.environ['UNSTRUCTURED_API_KEY']}"},
        },
        connect_timeout=60,
    ) as mcp_tools:
        llm = LLM(model=LLM_MODEL)

        agent = Agent(
            role="Document Processor",
            goal="Parse documents with the Unstructured Transform tools and return a summary.",
            backstory=(
                "You are an expert at using the Unstructured Transform MCP tools to parse "
                "and extract information from documents."
            ),
            tools=[*mcp_tools, upload_file, download_results],
            llm=llm,
            verbose=True,
        )

        task = Task(
            description=(
                f"Parse the file at {FILE_PATH} using the Unstructured Transform tools. "
                "To do this: call request_file_upload_url to get a signed upload URL and a "
                "file_ref; call upload_file with the local path and that upload URL to send "
                "the bytes (do not include an Authorization header — the URL is pre-signed); "
                "call start_transform_job with the file_ref; poll check_job_status until the "
                "job status is COMPLETED; call get_job_results to obtain the download URL; "
                "call download_results with that URL to retrieve the parsed content. "
                "Return a short summary of the document."
            ),
            agent=agent,
            expected_output="A short summary of the document's contents.",
        )

        crew = Crew(agents=[agent], tasks=[task], verbose=True)
        result = crew.kickoff()
        print(result)


if __name__ == "__main__":
    main()

​

Parse your source files

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

​

Troubleshooting

• crewai: command not found or ModuleNotFoundError: No module named 'crewai'. The install instructions on this page do not use a virtual environment, but if you chose to set one up yourself, it may not be activated. Run source <venv>/bin/activate on Mac or Linux, or <venv>\Scripts\activate on Windows, then retry.
• ImportError: Unable to initialize LLM with model '...'. The LLM_MODEL string has an unrecognized provider prefix or model name. The error message suggests installing LiteLLM, but the fix is to correct the provider/model-name string. For supported providers and their model name formats, see LLMs in the CrewAI documentation.
• ImportError: cannot import name 'streamablehttp_client'. The mcp package version 2.0.0 and later introduced a change that causes this error. Confirm your mcp version is below 2.0.0 by running pip show mcp, then downgrade with pip install "mcp>=1.10.1,<2.0.0" if needed.
• 401 Unauthorized on tool calls. Confirm the UNSTRUCTURED_API_KEY environment variable is set and that the Authorization header is formatted as Bearer <your-unstructured-api-key>.
• 403 Forbidden when uploading a file. You included an Authorization header on the httpx.put() call for the pre-signed upload URL. Remove it. The URL encodes its own credentials.
• Connection timeout when opening the adapter. Increase connect_timeout in the MCPServerAdapter call (the default is low). A value of 60 is usually sufficient for the hosted Transform server.
• ValueError: Unknown transport 'streamable_http'. The transport string requires a hyphen: "streamable-http", not an underscore.
• mcp_tools is empty after connecting. Verify the URL is exactly https://mcp.transform.unstructured.io and that your network allows outbound HTTPS to mcp.transform.unstructured.io.
• RuntimeError: Python 3.12 or later is required. The mcpadapt library that backs streamable HTTP support requires Python 3.12 or later, even though CrewAI itself supports Python 3.10. Upgrade your Python version.
• 502 Bad Gateway during polling. This is a transient server error. The transform job continues running server-side and is not lost. Wait a moment, then re-run the script to submit a new job.
• Task was destroyed but it is pending! or RuntimeWarning messages after the script finishes. These are expected cleanup messages from the interaction between mcpadapt and the MCP SDK when the adapter closes. They do not affect your results and can be safely ignored.

​

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 structured data extraction: Control how the Unstructured Transform MCP server extracts and formats structured data from 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.