> **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 MachGen MCP server

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

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

## 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 MachGen MCP connection

   In **AgentKit > Connections**, create a MachGen 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

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

   Then enter the app's Client ID and Client Secret on the MachGen 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 = 'machgenmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize MachGen 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: 'machgenmcp_check_balance',
     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 = "machgenmcp"
   identifier = "user_123"

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

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="machgenmcp_check_balance",
       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: 'machgenmcp_check_balance',
  toolInput: {},
  connector: 'machgenmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="machgenmcp_check_balance",
    tool_input={},
    connection_name="machgenmcp",
    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.

### `machgenmcp_check_balance`

Check balance · Read-only

Check the calling account's current spendable balance. The API key identifies exactly one account, so no account needs naming.

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

Inputs: none.

Example input: `{}`

### `machgenmcp_download_asset`

Download asset · Read-only

Download any owned completed MachGen image, video, or audio as a standard MCP file resource. Files up to 8 MiB are returned as an embedded binary resource. Larger files return a manifest with an expiring raw HTTPS URL without adding a media ResourceLink to model context. Save that URL with the client's local file/download capability using the returned filename; do not pass it back as media input. Every path preserves MIME type and original bytes. Use this when the user wants a file to save or reuse; get_asset is preview.

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

Inputs:

- `task_id` (`string`, required): No description.

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

### `machgenmcp_get_asset`

Get asset · Read-only

Fetch a completed asset for inline preview, plus its URL, size, and image vision bytes when small enough.

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

Inputs:

- `task_id` (`string`, required): No description.

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

### `machgenmcp_get_price`

Get generation price · Read-only

Quote what a generation would cost on the calling account, before submitting it. Returns the amount that would actually be charged, including any account-specific pricing and active discounts. The API key identifies exactly one account, so no account needs naming. For models that bill reference/input video (Seedance 2.0 R2V), pass input_video_secs (each attached clip's length rounded up to whole seconds, then summed - the billed aggregation) to quote that rate; it adds billed seconds on top of the output duration, and some models apply a minimum total (Kling 4.0 bills max(input + output, k x output) seconds with k = 2). Some models price a task type separately (MiniMax-H3 T2V is cheaper than its I2V/R2V), so pass task_type to quote the surface you will submit.

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

Inputs:

- `height` (`integer`, required): No description.
- `model` (`string`, required): No description.
- `aspect_ratio` (`string`, optional): No description.
- `audio` (`string`, optional): No description.
- `duration_secs` (`string`, optional): No description.
- `input_video_secs` (`string`, optional): No description.
- `task_type` (`string`, optional): No description.
- `width` (`string`, optional): No description.

Example input: `{"height":1,"model":"<model>"}`

### `machgenmcp_get_task`

Get task · Read-only

Check a task's status. Poll this after generating. Once a task completes, its image or video is exposed to the inline preview app. Final billing is returned in micro-USD once finished (1 USD = 1000000). billed_micros is cost after refunds; net_cost_micros also subtracts Generation Credit. Images also include vision bytes when small enough. Pass wait_secs to block until the task finishes instead of polling in a loop: the call returns the moment it completes or fails, or once the wait elapses - whichever comes first. A still-running task simply comes back RUNNING, so call again to keep waiting.

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

Inputs:

- `task_id` (`string`, required): No description.
- `include_image` (`boolean`, optional): No description. Default: `true`.
- `wait_secs` (`string`, optional): No description.

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

### `machgenmcp_get_task_params`

Get task parameters · Read-only

The exact settings a past task ran with, so you can re-run it with one thing changed rather than reconstructing the request.

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

Inputs:

- `task_id` (`string`, required): No description.

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

### `machgenmcp_get_tasks`

Get tasks · Read-only

Check up to 50 distinct task IDs in input order. Missing or inaccessible tasks return per-item not_found errors. wait_secs waits for all accessible tasks to finish or a shared deadline (maximum 120 seconds). Returns fixed asset URLs without creating temporary links; use get_asset for previews and download links. include_image defaults to false; inline images share a 4 MiB raw image-byte budget; the base64-encoded response can be larger.

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

Inputs:

- `task_ids` (`array`, required): No description.
- `include_image` (`boolean`, optional): No description. Default: `false`.
- `wait_secs` (`string`, optional): No description.

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

### `machgenmcp_list_history`

List history · Read-only

Browse this account's past generations, newest first. Use `search` to match a prompt or task id.

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

Inputs:

- `height` (`string`, optional): No description.
- `page` (`integer`, optional): No description. Default: `1`.
- `page_size` (`integer`, optional): No description. Default: `20`.
- `search` (`string`, optional): No description.
- `task_type` (`string`, optional): No description.

Example input: `{}`

### `machgenmcp_list_models`

List models · Read-only

List the models this account may use, with the exact output sizes, aspect ratios and durations each supports per task type. Call this before generating: heights and durations are exact allowed values, not ranges.

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

Inputs:

- `kind` (`string`, optional): No description.

Example input: `{}`

### `machgenmcp_ping`

Ping MachGen · Read-only

Check that the MachGen server is reachable and the credential is valid. Returns the authenticated account's email.

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

Inputs: none.

Example input: `{}`

### `machgenmcp_quote_video_upscale`

Quote video upscale · Read-only

Quote the exact source-aware cost of upscaling an owned completed video. Pass its task id or MachGen asset URL as source, a model, and a target_height tier from list_models UPSCALE. Source duration, fps and dimensions are resolved server-side; do not reconstruct a generic video payload. Optional engine and params must match that surface's advertised engines. Some UPSCALE surfaces accept only sources generated by specific models and tiers (see the surface's source_requirement); any other source is rejected with 400.

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

Inputs:

- `model` (`string`, required): No description.
- `source` (`string`, required): No description.
- `target_height` (`integer`, required): No description.
- `engine` (`string`, optional): No description.
- `params` (`string`, optional): No description.

Example input: `{"model":"<model>","source":"<source>","target_height":1}`

### `machgenmcp_complete_upload`

Complete image upload · Write

Finish an image upload started by create_upload after the HTTP PUT succeeds. Pass upload_token from create_upload. Checks ownership, expiry, size, and image validity using the same upload path as the UI. Returns input_ref (@input/...) for generate_image sources or generate_video src_image_urls, and artifact_path. Does not generate anything. Use only the returned input_ref as generation input.

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

Inputs:

- `upload_token` (`string`, required): No description.

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

### `machgenmcp_create_asset_link`

Create asset link · Write

Mint a time-limited URL for an asset that works without signing in, for handing to someone or opening in a browser. Defaults to 24 hours. The link grants read access to this one asset and nothing else.

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

Inputs:

- `task_id` (`string`, required): No description.
- `ttl_secs` (`integer`, optional): No description. Default: `86400`.

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

### `machgenmcp_create_upload`

Create image upload · Write

Upload a local image from Codex or another agent with shell/HTTP access. Provide file_name and the exact size_bytes. Returns a signed upload_url, PUT method, required headers, and upload_token. Read the original image in the agent's execution environment and PUT its raw bytes to that URL with every returned header. Do not send your MachGen credentials or put the file bytes in tool arguments. Then call complete_upload with upload_token to validate and obtain an @input/... reference. The file must be readable in the execution environment and the upload host must be reachable. Only images are supported. Without file or HTTP access, or to upload video/audio, use upload_files instead.

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

Inputs:

- `file_name` (`string`, required): No description.
- `size_bytes` (`integer`, required): No description.

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

### `machgenmcp_edit_image`

Edit image · Write

Edit a previous image generation. Pass the earlier task's id as `source`; the model receives that image and your prompt describes the change. Use extra_sources for models that compose several input images. Returns a task_id - poll get_task.

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

Inputs:

- `prompt` (`string`, required): No description.
- `source` (`string`, required): No description.
- `aspect_ratio` (`string`, optional): No description.
- `enhance_prompt` (`string`, optional): No description.
- `extra_sources` (`string`, optional): No description.
- `height` (`string`, optional): No description.
- `model` (`string`, optional): No description.
- `seed` (`string`, optional): No description.
- `width` (`string`, optional): No description.

Example input: `{"prompt":"<prompt>","source":"<source>"}`

### `machgenmcp_extract_video_clip`

Extract video clip · Write

Extract an exact [start_secs, end_secs] subsection from an owned, completed video task. The result is a new video asset with audio preserved, costs no generation credits, and can be polled, downloaded, shared, or reused like any other video.

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

Inputs:

- `end_secs` (`number`, required): No description.
- `source` (`string`, required): No description.
- `start_secs` (`number`, required): No description.

Example input: `{"end_secs":1,"source":"<source>","start_secs":1}`

### `machgenmcp_generate_audio`

Generate audio · Write

Generate audio. `kind` picks the surface: 'speech' reads the prompt in one voice, 'dialogue' voices `turns` as a multi-speaker scene (its text lives in the turns, not the prompt), 'sound_effect' and 'music' generate from the prompt. A surface's audio_config_fields from list_models are the only audio fields it takes; null means the provider's usual fields apply. `force_instrumental=true` makes instrumental music on the surfaces that take it: YuE2-3B lists it next to `lyrics`, and ElevenMusic takes it as a usual field. Where `lyrics` is listed, supply it for vocal songs within min_lyrics_chars and max_lyrics_chars; in instrumental mode it is optional planning text, words or section tags with no minimum but still within max_lyrics_chars. The prompt describes the style. For music surfaces without duration bounds, omit `duration_secs`; otherwise pass `duration_secs` within min_duration_secs and max_duration_secs. `output_format` takes one of the surface's output_formats; omitted renders default_output_format. Returns a task_id - poll get_task. Call list_models for the models and their limits.

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

Inputs:

- `kind` (`string`, required): No description.
- `model` (`string`, required): No description.
- `duration_secs` (`string`, optional): No description.
- `force_instrumental` (`string`, optional): No description.
- `lyrics` (`string`, optional): No description.
- `output_format` (`string`, optional): No description.
- `prompt` (`string`, optional): No description. Default: ``.
- `turns` (`string`, optional): No description.
- `voice_id` (`string`, optional): No description.

Example input: `{"kind":"<kind>","model":"<model>"}`

### `machgenmcp_generate_image`

Generate image · Write

Generate an image. Returns a task_id immediately - poll get_task until it completes, then the image comes back inline. Optional sources accept public image URLs, uploaded @input/ references, or your completed image task IDs/asset URLs. Inline data URLs are not supported by this asynchronous tool. No prior generation is required. With images, the model must support I2I; check list_models for max_input_images. Sources correspond to @image1, @image2, etc. in order. Describe their roles in the prompt; style guidance depends on the model and is not guaranteed. Local file paths are not uploads. Use edit_image to inherit an existing generation's settings.

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

Inputs:

- `height` (`integer`, required): No description.
- `model` (`string`, required): No description.
- `prompt` (`string`, required): No description.
- `aspect_ratio` (`string`, optional): No description.
- `enhance_prompt` (`string`, optional): No description.
- `negative_prompt` (`string`, optional): No description.
- `seed` (`string`, optional): No description.
- `sources` (`string`, optional): No description.
- `width` (`string`, optional): No description.

Example input: `{"height":1,"model":"<model>","prompt":"<prompt>"}`

### `machgenmcp_generate_video`

Generate video · Write

Generate a video. Returns a task_id immediately - poll get_task, which takes minutes for most models. The task type follows the inputs: no sources is text-to-video, a source image animates that image; audio references, subject bindings, reference_order, or reference_video_operation select R2V. Video sources select R2V when the model has R2V but no V2V surface; otherwise V2V. src_image_urls, src_video_urls, and src_audio_urls accept public HTTP(S) media URLs, uploaded @input/... references, or your completed MachGen task IDs/asset URLs. Inline data URLs and local file paths are not supported. subject_to_image_ids, subject_to_video_ids, and subject_to_audio_ids bind names to zero-based indices in each source list. reference_order contains {type: image|video|audio, index: integer} entries covering every source exactly once. reference_video_operation is reference, edit, or extend; check list_models for supported controls. For multi-shot, set shot_type=customize and pair multi_prompt with shot_durations summing to duration_secs; intelligence uses prompt. To animate a local image, call create_upload, PUT its raw bytes to upload_url with the returned headers and without MachGen credentials, then complete_upload; use its input_ref in src_image_urls. Without file/HTTP access, use upload_files and show its link to the user. Do not use upload_url, artifact_path, or download_asset download URL as input. Call list_models for allowed surfaces, reference counts, sizes and durations.

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

Inputs:

- `duration_secs` (`integer`, required): No description.
- `height` (`integer`, required): No description.
- `model` (`string`, required): No description.
- `prompt` (`string`, required): No description.
- `aspect_ratio` (`string`, optional): No description.
- `audio` (`string`, optional): No description.
- `enhance_prompt` (`string`, optional): No description.
- `fps` (`string`, optional): No description.
- `multi_prompt` (`string`, optional): No description.
- `negative_prompt` (`string`, optional): No description.
- `reference_order` (`string`, optional): No description.
- `reference_video_operation` (`string`, optional): No description.
- `seed` (`string`, optional): No description.
- `shot_durations` (`string`, optional): No description.
- `shot_type` (`string`, optional): No description.
- `src_audio_urls` (`string`, optional): No description.
- `src_image_urls` (`string`, optional): No description.
- `src_video_urls` (`string`, optional): No description.
- `subject_to_audio_ids` (`string`, optional): No description.
- `subject_to_image_ids` (`string`, optional): No description.
- `subject_to_video_ids` (`string`, optional): No description.
- `task_type` (`string`, optional): No description.
- `width` (`string`, optional): No description.

Example input: `{"duration_secs":1,"height":1,"model":"<model>","prompt":"<prompt>"}`

### `machgenmcp_upload_files`

Upload files in browser · Write

Let the user upload their own images, videos, or audio in a browser. Use when you cannot read the file or make HTTP uploads, including plain chat clients without shell access. With no session_id, creates an upload session and returns upload_url. Show that link to the user and ask them to open it, sign in to the same MachGen account, choose their files, and return to the chat when finished. You do not need browser or HTTP tools. This does not read attachments already in the chat; the user must select their files on the page. After the user confirms uploading, call this tool again with session_id to retrieve files and their input_ref values. Use those references in generate_image sources or generate_video src_image_urls, src_video_urls, and src_audio_urls according to each file's kind. An empty files list means nothing has been uploaded yet. Links accept uploads for two hours. Retrieve results within seven days of creating the link; references already retrieved remain usable. This tool uploads nothing itself and does not generate or charge.

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

Inputs:

- `session_id` (`string`, optional): No description.

Example input: `{}`

### `machgenmcp_upscale_video`

Upscale video · Write

Upscale an owned completed video without constructing a generic video-generation request. Pass its task id or MachGen asset URL as source, a model, and a target_height tier from list_models UPSCALE. The server resolves source duration, fps and dimensions. Some UPSCALE surfaces accept only sources generated by specific models and tiers (see the surface's source_requirement); any other source is rejected with 400. Call quote_video_upscale first for the exact cost. Returns a task_id - poll get_task until completion, then use download_asset for a file.

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

Inputs:

- `model` (`string`, required): No description.
- `source` (`string`, required): No description.
- `target_height` (`integer`, required): No description.
- `engine` (`string`, optional): No description.
- `params` (`string`, optional): No description.

Example input: `{"model":"<model>","source":"<source>","target_height":1}`

## 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 |
