> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Unstructured MCP server

The Unstructured MCP connector routes your AI agent's tool calls to Unstructured's own MCP server through Scalekit. Each user signs in to Unstructured once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 8 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** AI, Files & Documents
**Tools:** 8: 4 read, 4 write, 0 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Unstructured MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=UNSTRUCTUREDMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Unstructured MCP connection

   In **AgentKit > Connections**, create an Unstructured MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Unstructured MCP server connections use your own OAuth app. Register one with Unstructured MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Unstructured MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'unstructuredmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Unstructured MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'unstructuredmcp_get_instructions',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "unstructuredmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Unstructured MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="unstructuredmcp_get_instructions",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'unstructuredmcp_check_job_status',
  toolInput: {
    job_id: '<job_id>',
  },
  connector: 'unstructuredmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="unstructuredmcp_check_job_status",
    tool_input={
        "job_id": "<job_id>",
    },
    connection_name="unstructuredmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `unstructuredmcp_check_job_status`

Check job status · Read-only

Check a job's current status. Returns immediately.

Works for any job — a transform job (from ``start_transform_job``) or an
extraction job (from ``start_extraction_job``). Non-blocking: one status
snapshot per call, never a long wait. While the job is running, the
response carries ``poll_after`` — wait that many seconds, then call again
with the same ``job_id``. Polling faster is pointless: the server caches
the status for the same window. The job runs server-side and is never
lost between checks, so use the wait to do other work (mint upload URLs,
upload files, submit other batches). On ``COMPLETED``, call
``get_job_results`` next.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, required): Job handle returned by ``start_transform_job`` or
``start_extraction_job``.

Example input: `{"job_id":"<job_id>"}`

### `unstructuredmcp_get_instructions`

Get server instructions · Read-only

Return this server's full usage instructions and metadata on demand.

**Call this if you don't have the server's usage guidance in
context.** A server's instructions are delivered once, during the
connection handshake, and what happens next is up to the MCP host:
some hosts never relay them to the agent, and others truncate them
after a few thousand characters. If you're missing the URI-scheme
decision tree, the polling contract, the ``stages`` pipeline config,
or the enforced limits — or you're unsure whether what you have is
complete — call this tool to recover the full guidance in-band.

Returns:
    ``instructions`` — the complete instructions text, identical to
    what the connection handshake sends; ``name`` and ``version`` —
    server/product identity; ``models`` — the provider→model catalogs
    the registry offered at build (``vlm_partitioner`` as
    ``{provider: [model, …]}`` for ``partition.strategy: "vlm"``,
    ``embedder`` as ``{provider: {model: dimension}}`` for the ``embed``
    stage), so you can discover selectable models here rather than
    parsing the ``start_transform_job`` description; a ``null`` catalog
    means the build-time snapshot was unavailable (registry
    unreachable), not that no models exist — per-request validation
    stays the live authority; ``limits`` — every enforced limit on
    the surface: the aggregate caps (``max_file_mb`` /
    ``max_files_per_call`` / ``max_active_jobs_per_tenant``), the
    timing values (``poll_after_seconds`` and the signed-URL TTLs),
    and ``rate_limits_per_minute`` — the per-tenant per-minute
    backstop for every tool (keyed by tool name), the shared
    ``global`` ceiling, and the ``upload_route`` /
    ``output_download_route`` HTTP-route caps; and ``links`` — the
    ``dashboard`` (where the user manages their API key and finds
    billing and usage information) and ``docs`` URLs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `unstructuredmcp_get_job_results`

Get job results · Read-only

Fetch a completed job's results — works for transform and extraction jobs.

Call this after ``check_job_status`` returns ``COMPLETED``. One tool
serves both job kinds; it detects which from the job's DAG and shapes the
result accordingly. Every response carries a ``job_type`` field
(``"transform"`` or ``"extraction"``) so you always know which shape you
got — never infer it from element counts. The kinds:

- **Transform job** (from ``start_transform_job``): renders the parsed
  Element JSON as JSON / markdown / HTML / text. ``output_format`` is
  re-selectable — a job already retrieved as ``json`` can be re-fetched as
  ``md`` without re-running the engine. Each returned file also carries
  a durable ``output_ref`` (``u10d://output/<id>``) you can re-fetch or
  feed back into ``start_transform_job`` (to chunk/embed it) or
  ``start_extraction_job`` (to extract from it) without re-uploading or
  re-parsing. Output is delivered **out of band, not inline**: each entry
  returns a short-TTL signed ``download_url`` (plus counts) instead of the
  content, so a large document never floods your context. Fetch it e.g.
  ``curl -o output.<ext> '<download_url>'`` (download host is this MCP
  server). If your shell and the destination are different filesystems,
  do **not** read the output into context to re-emit it — hand the user a
  curl script; each entry's ``next_steps`` spells this out. (When output
  storage isn't configured — local dev — the entry inlines ``content``.)
  Fetching the outputs yourself is the generally preferred path
  (headless environments, allowlist-capable sandboxes); if your client
  renders MCP Apps and the user wants the files on their own machine,
  call ``open_file_manager`` with ``manager="downloader"`` and this
  ``job_id`` — the card enumerates the outputs and mints its own fresh
  URLs (don't copy ``download_url`` values into tool arguments), and
  the user picks and saves them straight from their browser.
- **Extraction job** (from ``start_extraction_job``): returns the
  extracted data per file as a **provenance-wrapped** object —
  ``filename``, ``filetype``, ``processed_date_utc``, ``source_file_uri``
  (the Element JSON ref you extracted from), and ``extracted_data``. Keep
  that wrapper intact downstream — do not unwrap to bare ``extracted_data``
  and discard the provenance, which is what ties each result back to its
  document (see the response ``next_steps``). ``output_format`` and
  ``image_base64`` do not apply and are ignored. If the extractor FAILED
  to produce output (e.g. a provider error), this returns an
  ``extraction_failed`` error — it never falls back to returning the
  parsed document as if extraction had succeeded.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, required): Job handle returned by ``start_transform_job`` or
``start_extraction_job``.
- `image_base64` (`string`, optional): Transform ``json`` output only — how much base64 image
payload to keep. Per-element ``metadata.image_base64`` page images
can be megabytes each on the generative_ocr path and are rarely
wanted in an agent's context; the full-fidelity image stays
re-fetchable from the durable ``output_ref``. One of: ``image``
(default) keeps base64 only on ``Image`` elements (e.g. for a RAG
pipeline embedding the crops) and strips it from every other type;
``none`` strips it from every element; ``all`` returns everything
the engine stored. No effect on ``md`` / ``html`` / ``txt`` (which
never embed base64) or on extraction jobs. Default: `image`.
- `output_format` (`string`, optional): Transform jobs only — one of ``json`` (default),
``md``, ``html``, ``txt``. Ignored for extraction jobs. Default: `json`.

Example input: `{"job_id":"<job_id>"}`

### `unstructuredmcp_open_file_manager`

Open file manager · Read-only

Show an interactive card so the user can upload or download files themselves.

Two routes move file bytes on this server; pick by environment:

- ``request_file_upload_url`` and ``get_job_results`` are the
  generally **preferred** out-of-band paths — best suited to
  fully agent-run, headless environments, and to hosts whose
  sandboxed environment can add this server's domain to the
  network egress/ingress allowlist so you move the bytes
  yourself.
- This tool is for any host that renders MCP Apps (e.g.
  claude.ai web/desktop/mobile) **with a human in the loop**:
  the user moves the bytes manually through their browser — no
  shell access or sandbox network configuration involved.

Unsure which environment you're in? Escalate in order: try the
out-of-band path first; if your PUT/GET is blocked by the
sandbox, call this tool; if no card renders either, you
genuinely cannot move the bytes — say so and ask the user for a
public URL (upload) or hand them the signed links (download).

``manager="uploader"`` renders a drag-and-drop upload card. Wait
for the user; their ``u10d://file/<id>`` refs arrive as a
conversation message, or — on hosts that drop app-to-model
messages — the user pastes them from the card's "Copy refs"
button. Pass the refs to ``start_transform_job``.

``manager="downloader"`` renders a pick-list of one job's output
files: pass the ``job_id`` after ``get_job_results`` has run for
it. The card enumerates the job's outputs and mints its own
fresh signed URLs — don't copy download_url values anywhere.
Every row starts checked; the user unchecks what they don't want
and hits Download. No follow-up from you is needed unless they
ask.

If no card renders, this host does not support MCP Apps — fall
back to the out-of-band paths above.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `manager` (`string`, required): Which card to open — ``"uploader"`` or ``"downloader"``. One of: `uploader`, `downloader`.
- `job_id` (`string`, optional): Downloader only — the completed job whose outputs to
offer, already fetched once with ``get_job_results``.
Ignored for the uploader.

Example input: `{"manager":"uploader"}`

### `unstructuredmcp_request_file_upload_url`

Request file upload URL · Write

Upload a file to the Unstructured Platform for parsing.

Returns a signed PUT URL; the agent PUTs the file bytes there,
then passes the returned ``file_ref`` to ``start_transform_job``.
The URL points at the MCP host itself — no third-party
blob-storage hostname needs to be allowlisted.

This tool is the generally preferred upload path: it suits
fully agent-run, headless environments, and hosts whose
sandboxed environment can add this server's domain to the
network egress allowlist so you PUT the bytes yourself (CLI
and IDE hosts, scripts). **If your client renders MCP Apps
(e.g. claude.ai web/desktop/mobile) and a human is present,
use ``open_file_manager`` with
``manager="uploader"`` instead** — the user uploads straight
from their browser, which needs no shell access and is not
subject to sandbox network egress rules.

Call this when the user has provided a file you can read by
path — either typed/quoted in chat, @-mentioned, drag-dropped
(most terminals paste the path as text), or already sitting in
your sandbox. Skip this tool entirely if the file is reachable
at a public ``https://`` URL (pass the URL straight to
``start_transform_job``).

**If the file came inline as a vision attachment with no path
in the message:** you cannot save it yourself. Vision
attachments reach you through the multimodal encoder, not as
text/base64 in your tool-accessible context, so ``Write`` /
``Bash`` have no bytes to write. Most MCP hosts (e.g. Claude
Code, Cursor, VS Code Copilot, Cline, Continue) do **not** expose a
readable path either. Don't guess at temp directories — ask
the user once, concisely, to save the file and share the
path. Hosts where a path *is* already available without
asking:

- Anthropic Code Execution / claude.ai (Cowork): attachments
  mount under ``/mnt/user-data/uploads/`` — check there first.
- Zed: ``@``-mentioned files keep their workspace path.
- Codex CLI: user-supplied ``--image <path>`` is in the message.

Limits: a single file may not exceed 50 MB. Upload-URL minting
also has a per-tenant per-minute abuse backstop, set well above
any legitimate parsing rate (current value in the server
instructions); if a call returns ``rate_limited``, wait for the
returned ``retry_after`` before minting more URLs —
already-minted URLs stay usable until ``expires_at``.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `content_type` (`string`, required): MIME type of the file.
- `filename` (`string`, required): Original name of the file being uploaded.
- `size_bytes` (`integer`, required): Length of the file in bytes; pre-flighted against
the 50 MB cap before the URL is minted.

Example input: `{"content_type":"<content_type>","filename":"<filename>","size_bytes":1}`

### `unstructuredmcp_start_extraction_job`

Start job to extract data from files · Write

Extract structured JSON from parsed documents against a JSON schema.

Runs the platform's structured data extractor over already-parsed
**Unstructured Element JSON** and returns only the extracted data. Submits
1–10 inputs as one async job and returns a ``job_id``
immediately; drive the wait via ``check_job_status``, then call
``get_job_results`` to retrieve the extracted JSON.

**Inputs are Element JSON, never raw documents.** Each ref in
``element_json_refs`` must resolve to the Element JSON a parse produces —
a ``u10d://output/<id>`` from a previous ``get_job_results``, or a
``u10d://file/<id>`` / ``http(s)://`` pointing at Element JSON. To extract
from a raw PDF/DOCX/etc., run ``start_transform_job`` first and pass its
``output_ref`` here. Embed-stage output (Element JSON carrying vectors) is
rejected — pass the parse (or chunk) output, i.e. the Element JSON from
*before* any embed stage. Limits mirror ``start_transform_job``:
50 MB per file, 10 per call, 5 active jobs
per tenant.

**Parse quality drives extraction quality.** The extractor can only pull
out what the parse captured, and documents to extract from are almost
always images / PowerPoint / PDFs, so parse them the same way: (1) **start
with** ``start_transform_job`` and ``stages={"partition": {"strategy":
"vlm"}}`` (a vision model reads the page); (2) **if the extraction isn't
optimal, re-parse with** ``strategy=hi_res`` plus ``enrich`` types
``["image_description", "generative_ocr", "table_to_html"]`` (per-element
AI passes — image/OCR are VLM-based, table_to_html may use a VLM or
agentic AI), which can massively outperform ``vlm`` when hi_res object
detection nails the layout and element classification. A cheap
``fast``/``auto`` parse misses tables, figures, and scanned text and yields
sparse extractions — re-parse at high fidelity if the Element JSON you're
about to pass came from a low-quality run.

**One schema per call.** ``schema_to_extract`` is a single JSON Schema
(as a JSON string) applied to every file in the batch, so all files must
be the same kind of document / suit that one schema. It's validated
against OpenAI Structured-Output constraints *before* the job is
scheduled — a malformed schema returns an ``invalid_request`` error
naming the problem, not a raw upstream 422. Don't have a schema? Call
``suggest_extraction_schema_for_file`` first. Provider and model are not
selectable here — the platform applies its working default.

**Result shape.** ``get_job_results`` returns a self-describing object per
file — ``filename``, ``filetype``, ``processed_date_utc``,
``source_file_uri`` (the Element JSON ref you passed), and
``extracted_data``. If the user also wants the full parsed document,
render the *parse* job it came from (retain that ``job_id`` and call
``get_job_results``), or feed ``source_file_uri`` back through
``start_transform_job`` and render that job — ``source_file_uri`` is an
input ref, not a ``get_job_results`` argument. It isn't inlined here, so
the extraction stays small.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `element_json_refs` (`array`, required): 1–10 URIs, each resolving to Unstructured
Element JSON (typically prior ``output_ref``s). Not raw documents.
- `schema_to_extract` (`string`, required): A single OpenAI-compatible JSON Schema, as a JSON
string, applied to every input.
- `extraction_guidance` (`string`, optional): Optional free-text guidance passed to the
extractor to shape how fields are filled.

Example input: `{"element_json_refs":[],"schema_to_extract":"<schema_to_extract>"}`

### `unstructuredmcp_start_transform_job`

Start job to transform files · Write

Transform files into structured output by running a configurable pipeline.

Submits 1–10 inputs as one async job and returns a ``job_id``
immediately. Drive the wait via ``check_job_status``; once complete,
call ``get_job_results`` to retrieve the rendered output in the format
you want.

**Inputs.** ``file_refs`` accepts ``https://`` / ``http://`` URLs,
``u10d://file/<id>`` uploads (mint via ``request_file_upload_url`` +
PUT, or pasted by the user from the ``open_file_manager`` card's
"Copy refs" button), and ``u10d://output/<id>`` refs from a
previous ``get_job_results``. An ``output_ref`` resolves to that job's
*terminal* stage — the last stage it ran. Feeding it back in
re-ingests that Element JSON without re-partitioning, so re-chunking or
re-embedding is cheap and needs no re-upload — but the re-feed is only
sound when the ref is *upstream* of the stage you're changing: a
parse-only ref is a clean seed to re-chunk; an already-embedded ref is
not (re-chunking it mangles already-chunked output). See **Staging
strategy** below. Limits: 50 MB per file, 10 per call,
5 active jobs per tenant. Free-tier accounts also carry a
page allowance; once it's exhausted this tool returns a
``quota_exceeded`` error whose ``message`` and ``upgrade_url``
should be relayed to the user verbatim.

**Pipeline.** ``stages`` is a map of stage name → settings; the tool
wires the DAG in canonical order (``partition → enrich → chunk →
embed``) regardless of key order. Omit ``stages`` (or pass ``{}``)
for a plain parse. Stages:

- ``partition`` — ``{"strategy": ...}`` (``fast`` / ``hi_res`` / ``vlm``
  / ``auto``), plus optional ``languages`` and ``page_range``. Under
  ``vlm``, ``provider`` / ``model`` pin the vision model — e.g.
  ``{"strategy": "vlm", "provider": "anthropic", "model":
  "claude-sonnet-4-6"}``
  (omit both ``provider`` and ``model`` to have the deployment resolve a default VLM server-side; or pin one of ``anthropic`` (claude-haiku-4-5-20251001, claude-opus-4-1-20250805, claude-opus-4-5-20251101, claude-opus-4-6, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-opus-5-5, claude-sonnet-4-5-20250929, claude-sonnet-4-6, claude-sonnet-5, claude-sonnet-5-5); ``bedrock`` (us.amazon.nova-2-lite-v1:0, us.amazon.nova-lite-v1:0, us.amazon.nova-pro-v1:0, us.anthropic.claude-3-haiku-20240307-v1:0, us.anthropic.claude-3-opus-20240229-v1:0, us.anthropic.claude-3-sonnet-20240229-v1:0, us.anthropic.claude-opus-4-20250514-v1:0, us.anthropic.claude-opus-4-5-20251101-v1:0, us.anthropic.claude-opus-4-6-v1, us.anthropic.claude-opus-4-7, us.anthropic.claude-opus-4-8, us.anthropic.claude-opus-5, us.anthropic.claude-opus-5-5, us.anthropic.claude-sonnet-4-20250514-v1:0, us.anthropic.claude-sonnet-4-5-20250929-v1:0, us.anthropic.claude-sonnet-4-6, us.anthropic.claude-sonnet-5, us.anthropic.claude-sonnet-5-5); ``openai`` (gpt-4o, gpt-4o-mini, gpt-5-mini, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.6, gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-6-luna, gpt-6-sol); ``vertexai`` (gemini-2.0-flash-001, gemini-2.5-flash, gemini-2.5-pro, gemini-3-flash-preview, gemini-3-pro-preview, gemini-3.5-flash, gemini-3.7-flash, projects/vertex-ai-non-production/locations/us-east1/endpoints/4736504777435774976, projects/vertex-ai-non-production/locations/us/endpoints/4821384876076826624, projects/vertex-ai-non-production/locations/us/endpoints/968555394861367296) (the operator must have provisioned that provider's key)); other strategies ignore them. They go at the
  stage's top level, not inside the advanced ``options`` passthrough.
  A partition node always runs (it's a near-passthrough for
  Element-JSON inputs); this stage only customizes it. **Pick the
  strategy explicitly from the input type — don't rely on ``auto`` —
  and note the wrong choice degrades silently rather than erroring:**

  - **Images, PowerPoint (PPT/PPTX), and PDFs** → start with ``vlm``. If
    its output isn't optimal, switch to ``hi_res`` with the
    ``image_description`` / ``generative_ocr`` / ``table_to_html``
    enrichments, which can beat ``vlm`` when hi_res layout/element
    detection is accurate. ``hi_res`` is also the strategy that yields
    the bounding-boxed elements enrichments act on.
  - **Every other format** (DOCX, XLSX, HTML, EML, CSV, TXT, …) → use
    ``fast``. ``vlm``/``hi_res`` don't apply to these and silently fall
    back to ``fast`` anyway, and ``fast`` (text-layer extraction) is all
    they need.
- ``enrich`` — ``{"types": [...]}``; per-element AI passes (most are
  VLM-based; ``table_to_html`` may use a VLM or agentic AI, and ``ner``
  reads extracted text) that need ``hi_res`` to have elements to act on.
  Types: ``image_description``, ``table_description``, ``table_to_html``,
  ``ner``, ``generative_ocr``.
- ``chunk`` — ``{"strategy": ...}`` (required: ``chunk_by_character`` / ``chunk_by_page`` / ``chunk_by_similarity`` / ``chunk_by_title``)
  plus optional size settings (``max_characters``, ``overlap``,
  ``new_after_n_chars``, ``combine_text_under_n_chars``,
  ``similarity_threshold``, …). Slices elements into retrieval-sized
  chunks.
- ``embed`` — ``{"provider": ..., "model": ...}`` (defaults ``openai`` / ``text-embedding-3-small``; the model registry currently offers ``azure_openai`` (text-embedding-3-large:3072, text-embedding-3-small:1536, text-embedding-ada-002:1536); ``bedrock`` (amazon.titan-embed-text-v1:1536, amazon.titan-embed-text-v2:0:1024, cohere.embed-english-v3:1024, cohere.embed-multilingual-v3:1024); ``ibm`` (ibm/granite-embedding-278m-multilingual:768, ibm/slate-125m-english-rtrvr-v2:768, ibm/slate-30m-english-rtrvr-v2:384, intfloat/multilingual-e5-large:1024, sentence-transformers/all-minilm-l6-v2:384); ``openai`` (text-embedding-3-large:3072, text-embedding-3-small:1536, text-embedding-ada-002:1536); ``voyageai`` (voyage-3:1024, voyage-3-large:1024, voyage-3-lite:512, voyage-3.5:1024, voyage-3.5-lite:1024, voyage-code-2:1536, voyage-code-3:1024, voyage-finance-2:1024, voyage-law-2:1024) (as model:dimension, where the operator has provisioned that provider's key)).
  Attaches a vector to each chunk/element. Best paired with
  ``chunk`` — embedding whole un-chunked elements retrieves poorly
  (you'll get a warning). Embedded output is large and
  vector-dominated; it's retrieved out of band — never read it into
  context to re-emit it to a file (see ``get_job_results``).

Examples — parse: ``{}``. RAG ingest:
``{"chunk": {"strategy": "chunk_by_title"}, "embed": {}}``.
Re-chunk a prior output: ``file_refs=["u10d://output/…"]`` with
``{"chunk": {"strategy": "chunk_by_character", "max_characters": 1000}}``.

**Staging strategy — decide before you submit.** A job returns exactly
one ``output_ref`` per file: the Element JSON of its *terminal* stage.
Intermediate stages are not separately addressable, so a single
``partition+chunk+embed`` job hands back one (embedded) handle, not one
per stage. If you're confident in every stage's settings, run the whole
pipeline in one job. But if there's *any* doubt that a downstream stage
is optimal — a chunk size/strategy or embed model you may want to A/B or
re-tune — split the pipeline into separate jobs chained by
``output_ref`` (parse → its ref → chunk → its ref → embed). Each job
then yields its own reusable seed, so re-tuning a later stage re-runs
only that stage instead of forcing a re-parse — or, worse, re-chunking
already-embedded output.

**Embedding model must match at query time.** The provider + model in
an ``embed`` stage define the vector space; to search the vectors you
must embed each query with the *same* provider/model — call the
embedding provider's API directly at query time. A different model or
dimension is not comparable. The response ``warnings`` echo the exact
provider/model/dimension; record them and tell the user. **Cost:**
embedding calls a paid provider and scales with token count.

Output format is not chosen here — the engine always materializes
Element JSON and ``get_job_results`` renders ``md`` / ``json``
/ ``html`` / ``txt`` per call.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `file_refs` (`array`, required): 1–10 input URIs (source files or prior
``output_ref``s).
- `stages` (`string`, optional): Optional pipeline config (see above). Omit for a plain
parse. An unknown stage name or setting surfaces as an
``invalid_request`` error listing what's available.

Example input: `{"file_refs":[]}`

### `unstructuredmcp_suggest_extraction_schema_for_file`

Suggest extraction schema for file · Write

Suggest a JSON extraction schema for one parsed document.

Given **Unstructured Element JSON** for a single document, drafts a JSON
Schema (valid for ``start_extraction_job``) capturing the document's
salient fields. Use this when you want to extract structured data but
don't yet have a schema.

**Input is Element JSON for one document, not a raw file.**
``element_json_ref`` must resolve to the Element JSON a parse produces (a
``u10d://output/<id>``, or a ``u10d://file/<id>`` / ``http(s)://``
pointing at Element JSON). To suggest from a raw PDF/DOCX/etc., run
``start_transform_job`` first and pass its ``output_ref`` here. For the
richest schema, parse at high fidelity: for images/PPT/PDF start with
``strategy=vlm``, then if that's not optimal re-parse with
``strategy=hi_res`` plus the ``image_description`` / ``generative_ocr`` /
``table_to_html`` enrichments (which can outperform ``vlm`` when hi_res
layout detection is accurate) so tables and figures are captured.
Embedded output (Element JSON carrying vectors) is rejected.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `element_json_ref` (`string`, required): A single URI resolving to one document's
Unstructured Element JSON.
- `guidance` (`string`, optional): Optional free-text guidance to shape the schema (e.g. which
fields matter, desired field names).

Example input: `{"element_json_ref":"<element_json_ref>"}`

## Related

Other AI connectors ([all 216](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
