Model Context Protocol (MCP) Hands-On Walkthrough for the Unstructured Workflow Endpoint
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. From the MCP documentation:
Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
This article provides a hands-on, step-by-step walkthrough to build a simple example on your local development machine that integrates the Unstructured API with the Python SDK for Model Context Protocol. Specifically, this walkthrough demonstrates how to write and run Python code to create an MCP server (a lightweight program that exposes specific capabilities through MCP); this MCP server uses the Unstructured Workflow Endpoint to list all of your available source connectors and to get information about a specific source connector. The Workflow Endpoint offers a full range of partitioning, chunking, embedding, and enrichment options for your files and data.
For a hands-on walkthrough of the Unstructured Partition Endpoint instead, see the MCP Hands-On Walkthrough for the Unstructured Partition Endpoint, which is intended for rapid prototyping of Unstructured’s various partitioning strategies, with limited support for chunking, processing local files one file at a time.
You call this MCP server from an MCP client (an application that maintains a one-to-one connection with an MCP server), which in this walkthrough is Claude for Desktop, a chat-based interface, by asking it plain language questions. Other MCP clients are also available. Learn more.
At the end of this walkthrough, you can extend this example by using the Workflow Endpoint to perform other tasks, such as creating, listing, changing, and deleting various connectors, workflows, and jobs in your Unstructured account.
Requirements
To complete this walkthrough, you must first have an Unstructured account, an Unstructured API key for that account, the necessary Python toolchain and project setups, and Claude for Desktop, as follows.
Unstructured account and API key
Before you begin, you must have an Unstructured account and an Unstructured API key, as follows:
-
Go to https://platform.unstructured.io and use your email address, Google account, or GitHub account to sign up for an Unstructured account (if you do not already have one) and sign into the account at the same time. The Unstructured user interface (UI) appears.
-
Get your Unstructured API key:
a. In the Unstructured UI, click API Keys on the sidebar.
b. Click Generate API Key.
c. Follow the on-screen instructions to finish generating the key.
d. Click the Copy icon next to your new key to add the key to your system’s clipboard. If you lose this key, simply return and click the Copy icon again.
By following the preceding instructions, you are signed up for a Developer pay per page account by default.
To save money, consider switching to a Subscribe & Save account instead. To save even more money, consider switching to an Enterprise account instead.
Python toolchain and Claude for Desktop setup
Before you can start coding on your local machine, you must install the Python package and project manager uv
, and install Claude for Desktop, as follows.
Install uv
, as follows.
By using pip
:
Or, by using the following script (be sure to restart your terminal or Command Prompt after running the script):
(To learn more about uv
, see the uv documentation.)
You are now ready to start coding.
Step 1: Create the MCP server
If you are not interested in building an MCP server from the beginning and want to use a pre-built MCP server instead, skip ahead to Optional Step 4: Extend the MCP server.
From your current working directory, create a project directory and then initialize it. This example creates a
project directory named mcp-unstructured-demo
. Then go to the project directory:
Create a virtual environment in the root of the project directory. Then activate the virtual environment:
To deactivate and exit the virtual environment at any time, simply run the deactivate
command:
With the virtual environment activated, install the Python SDK for Model Context Protocol and additional code dependencies:
In the root of the project directory, create a new Python file. This example names the file workflow.py
.
Then add the following code to this new workflow.py
file:
In the root of the project directory, create a new file named .env
.
Then add the following code to this new .env
file, replacing <your-unstructured-api-key>
with your Unstructured API key:
Step 2: Configure Claude for Desktop to use the MCP server
Open the Claude for Desktop App configuration file from the following location, for example by using Visual Studio Code:
Add the following code to the claude_desktop_config.json
file, and then save the file.
In this file:
"workflow"
must match the value that you set inmcp = FastMCP("workflow" ...
in theworkflow.py
file.- “Absolute path to”
uv
must be the absolute path to theuv
executable on your local machine. - “Absolute path to project directory” must be the absolute path to the project directory.
mcp_unstructured-demo
must match the name of the project directory that you created."workflow.py"
must match the name of the Python file that you created for the MCP server.
For macOS or Linux:
For Windows:
Step 3: Run the MCP server and call it from Claude for Desktop
Start Claude for Desktop. If it is already running, restart it.
Ask the following question in the chat window, replacing S3
with the type of source connector that you want to list.
For a list of available source connector types, see the Workflow Endpoint Sources overview.
Claude for Desktop responds with a list of all available source connectors for that source connector type.
Ask another question in the chat window, replacing <source-connector-id>
with one of the source connector IDs that
Claude for Desktop returned in the previous step. For example:
Claude for Desktop responds with information about that source connector.
Optional Step 4: Extend the MCP server
Unstructured offers an initial experimental MCP server implementation, with much more functionality then the MCP server that you just created previously in this walkthrough. This initial MCP server is intended only for experimentation purposes and is not recommended for production usage. A more complete, supported, production-level implementation is coming soon.
To use Unstructured’s initial experimental MCP server implementation, do the following:
From a different working directory than the one you used in previously in this walkthrough, use Git to clone the Unstructured API MCP Server repository in GitHub, and then switch to the cloned repository’s root directory:
In the cloned repository’s root directory, create a new file named .env
.
Then add the following code to this new .env
file, replacing <your-unstructured-api-key>
with your Unstructured API key:
In the cloned repository’s root directory, create a virtual environment. Then activate the virtual environment:
To deactivate and exit the virtual environment at any time, simply run the deactivate
command:
With the virtual environment activated, install the cloned repository’s code dependencies:
Open the Claude for Desktop App configuration file from the following location, for example by using Visual Studio Code:
Overwrite the contents of the claude_desktop_config.json
file with the following content, and then save the file.
For macOS or Linux:
For Windows:
Start Claude for Desktop. If it is already running, restart it.
Here are some questions that you can ask in the chat window to test the MCP server. Replace the placeholders with the appropriate values.
For a list of available source connector types, see the Workflow Endpoint Sources overview.
For a list of available destination connector types, see the Workflow Endpoint Destinations overview.
List all available source connectors of type <source-connector-type>.
Provide information about the source connector with ID <source-connector-id>.
List all available source connectors of type <destination-connector-type>.
Provide information about the source connector with ID <destination-connector-id>.
List all available destination connectors of type <destination-connector-type>.
Provide information about the destination connector with ID <destination-connector-id>.
Create a new workflow.
Provide information about the workflow with ID <workflow-id>.
Run the workflow with ID <workflow-id>.
Update the workflow with ID <workflow-id>.
List all available workflows.
Delete the worklow with ID <workflow-id>.
Was this page helpful?