Unstructured Transform MCP server installation for Microsoft Agent Framework

pip install "agent-framework==1.11.0"

dotnet add package Microsoft.Agents.AI.OpenAI --version 1.13.0
dotnet add package ModelContextProtocol --version 2.0.0-preview.2

import os

import httpx
from agent_framework import MCPStreamableHTTPTool

http_client = httpx.AsyncClient(
    headers={"Authorization": f"Bearer {os.environ['UNSTRUCTURED_API_KEY']}"},
    timeout=httpx.Timeout(30.0, read=300.0),
)

transform = MCPStreamableHTTPTool(
    name="unstructured-transform",
    url="https://mcp.transform.unstructured.io",
    http_client=http_client,
)

# Connecting loads the Transform tools: request_file_upload_url,
# transform_files, check_transform_status, and get_transform_results.
async with transform:
    print(sorted(f.name for f in transform.functions))

using ModelContextProtocol.Client;

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://mcp.transform.unstructured.io"),
    TransportMode = HttpTransportMode.StreamableHttp,
    AdditionalHeaders = new Dictionary<string, string>
    {
        ["Authorization"] = $"Bearer {Environment.GetEnvironmentVariable("UNSTRUCTURED_API_KEY")}",
    },
});

await using var mcpClient = await McpClient.CreateAsync(transport);

// Lists the Transform tools: request_file_upload_url, transform_files,
// check_transform_status, and get_transform_results.
var transformTools = await mcpClient.ListToolsAsync();
Console.WriteLine(string.Join(", ", transformTools.Select(t => t.Name)));

import asyncio
import mimetypes
import os
from pathlib import Path
from typing import Annotated

import httpx
from agent_framework import MCPStreamableHTTPTool
from agent_framework.openai import OpenAIChatClient

TRANSFORM_MCP_URL = "https://mcp.transform.unstructured.io"


def describe_local_file(
    path: Annotated[str, "The path to a local file."],
) -> dict:
    """Get the filename, content type, and exact size in bytes of a local file."""
    file = Path(path).expanduser()
    content_type = mimetypes.guess_type(file.name)[0] or "application/octet-stream"
    return {
        "filename": file.name,
        "content_type": content_type,
        "size_bytes": file.stat().st_size,
    }


def upload_local_file(
    path: Annotated[str, "The path to the local file to upload."],
    upload_url: Annotated[str, "The pre-signed upload_url from request_file_upload_url."],
    content_type: Annotated[str, "The Content-Type header value to send."],
) -> str:
    """Upload a local file's raw bytes to a pre-signed URL with an HTTP PUT."""
    # The URL is pre-signed: do not send an Authorization header here.
    file = Path(path).expanduser()
    response = httpx.put(
        upload_url,
        content=file.read_bytes(),
        headers={"Content-Type": content_type},
        timeout=120.0,
    )
    response.raise_for_status()
    return f"Uploaded {file.name}, status {response.status_code}."


def download_text(
    url: Annotated[str, "The pre-signed download_url from get_transform_results."],
) -> str:
    """Download the transformed output from a pre-signed URL with an HTTP GET."""
    # The URL is pre-signed: do not send an Authorization header here.
    response = httpx.get(url, timeout=120.0)
    response.raise_for_status()
    return response.text


INSTRUCTIONS = """
You transform local documents into structured Markdown with the Unstructured
Transform tools. Follow this exact sequence:

1. Call describe_local_file to get the file's filename, content_type, and
   size_bytes. Report files larger than 52428800 bytes (50 MB) to the user
   instead of uploading them.
2. Call request_file_upload_url with that filename, content_type, and
   size_bytes.
3. Call upload_local_file with the file path and the returned upload_url and
   Content-Type header value.
4. Call transform_files with file_refs set to a one-item list containing the
   returned file_ref.
5. Poll check_transform_status with the returned job_id until status is
   COMPLETED. Transforms take from about 10 seconds to several minutes.
6. Call get_transform_results with the job_id, then call download_text with
   the first file's download_url to retrieve the Markdown output.
"""


async def main() -> None:
    # The Transform MCP server requires the Authorization header on every
    # request, including the initialize handshake, so configure it on the
    # HTTP client itself.
    http_client = httpx.AsyncClient(
        headers={"Authorization": f"Bearer {os.environ['UNSTRUCTURED_API_KEY']}"},
        timeout=httpx.Timeout(30.0, read=300.0),
    )

    transform = MCPStreamableHTTPTool(
        name="unstructured-transform",
        url=TRANSFORM_MCP_URL,
        http_client=http_client,
    )

    async with transform:
        agent = OpenAIChatClient().as_agent(
            name="transform-agent",
            instructions=INSTRUCTIONS,
            tools=[transform, describe_local_file, upload_local_file, download_text],
        )

        result = await agent.run(
            "Transform the document at ./sample.pdf and show me the first "
            "500 characters of the Markdown output, plus the element count."
        )
        print(result.text)


if __name__ == "__main__":
    asyncio.run(main())

using System.ComponentModel;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;
using OpenAI;
using OpenAI.Chat;

const string TransformMcpUrl = "https://mcp.transform.unstructured.io";

var apiKey = Environment.GetEnvironmentVariable("UNSTRUCTURED_API_KEY")
    ?? throw new InvalidOperationException("Set the UNSTRUCTURED_API_KEY environment variable.");

// The Transform MCP server requires the Authorization header on every
// request, including the initialize handshake.
var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri(TransformMcpUrl),
    TransportMode = HttpTransportMode.StreamableHttp,
    AdditionalHeaders = new Dictionary<string, string>
    {
        ["Authorization"] = $"Bearer {apiKey}",
    },
});

await using var mcpClient = await McpClient.CreateAsync(transport);

var transformTools = await mcpClient.ListToolsAsync();
Console.WriteLine($"Discovered tools: {string.Join(", ", transformTools.Select(t => t.Name))}");

// Local helper tools. The byte upload and result download use pre-signed
// URLs, which are plain HTTP calls rather than MCP tool calls.
using var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(120) };

[Description("Get the filename, content type, and exact size in bytes of a local file.")]
static object DescribeLocalFile([Description("The path to a local file.")] string path)
{
    var file = new FileInfo(path);
    var contentType = file.Extension.ToLowerInvariant() switch
    {
        ".pdf" => "application/pdf",
        ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        ".html" or ".htm" => "text/html",
        ".txt" => "text/plain",
        ".png" => "image/png",
        ".jpg" or ".jpeg" => "image/jpeg",
        _ => "application/octet-stream",
    };
    return new { filename = file.Name, content_type = contentType, size_bytes = file.Length };
}

[Description("Upload a local file's raw bytes to a pre-signed URL with an HTTP PUT.")]
async Task<string> UploadLocalFile(
    [Description("The path to the local file to upload.")] string path,
    [Description("The pre-signed upload_url from request_file_upload_url.")] string uploadUrl,
    [Description("The Content-Type header value to send.")] string contentType)
{
    // The URL is pre-signed: do not send an Authorization header here.
    using var content = new ByteArrayContent(await File.ReadAllBytesAsync(path));
    content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue(contentType);
    using var response = await httpClient.PutAsync(uploadUrl, content);
    response.EnsureSuccessStatusCode();
    return $"Uploaded {Path.GetFileName(path)}, status {(int)response.StatusCode}.";
}

[Description("Download the transformed output from a pre-signed URL with an HTTP GET.")]
async Task<string> DownloadText(
    [Description("The pre-signed download_url from get_transform_results.")] string url)
{
    // The URL is pre-signed: do not send an Authorization header here.
    return await httpClient.GetStringAsync(url);
}

const string Instructions = """
    You transform local documents into structured Markdown with the
    Unstructured Transform tools. Follow this exact sequence:

    1. Call DescribeLocalFile to get the file's filename, content_type, and
       size_bytes. Report files larger than 52428800 bytes (50 MB) to the
       user instead of uploading them.
    2. Call request_file_upload_url with that filename, content_type, and
       size_bytes.
    3. Call UploadLocalFile with the file path and the returned upload_url
       and Content-Type header value.
    4. Call transform_files with file_refs set to a one-item list containing
       the returned file_ref.
    5. Poll check_transform_status with the returned job_id until status is
       COMPLETED. Transforms take from about 10 seconds to several minutes.
    6. Call get_transform_results with the job_id, then call DownloadText
       with the first file's download_url to retrieve the Markdown output.
    """;

var openAiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")
    ?? throw new InvalidOperationException("Set the OPENAI_API_KEY environment variable.");
var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL") ?? "gpt-4.1-mini";

AIAgent agent = new OpenAIClient(openAiKey)
    .GetChatClient(model)
    .AsAIAgent(
        instructions: Instructions,
        tools:
        [
            .. transformTools.Cast<AITool>(),
            AIFunctionFactory.Create(DescribeLocalFile),
            AIFunctionFactory.Create(UploadLocalFile),
            AIFunctionFactory.Create(DownloadText),
        ]);

var response = await agent.RunAsync(
    "Transform the document at ./sample.pdf and show me the first "
    + "500 characters of the Markdown output, plus the element count.");
Console.WriteLine(response.Text);

export OPENAI_API_KEY="<your-openai-api-key>"
export OPENAI_CHAT_MODEL="gpt-4.1-mini"

python transform_agent.py

export OPENAI_API_KEY="<your-openai-api-key>"
export OPENAI_CHAT_MODEL="gpt-4.1-mini"

dotnet run

# The Python OpenAIChatClient reads these environment variables and routes
# to Azure OpenAI automatically. No code changes are needed.
export AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com"
export AZURE_OPENAI_API_KEY="<your-azure-openai-api-key>"
export AZURE_OPENAI_CHAT_MODEL="<your-deployment-name>"

// Add the Azure OpenAI package first:
//   dotnet add package Azure.AI.OpenAI
// Then replace the OpenAIClient lines with the following:
using Azure;
using Azure.AI.OpenAI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var azureKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_CHAT_DEPLOYMENT")!;

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureKey))
    .GetChatClient(deployment)
    .AsAIAgent(
        instructions: Instructions,
        tools:
        [
            .. transformTools.Cast<AITool>(),
            AIFunctionFactory.Create(DescribeLocalFile),
            AIFunctionFactory.Create(UploadLocalFile),
            AIFunctionFactory.Create(DownloadText),
        ]);