> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Every tool on Importly's MCP server: what it does, its inputs, what it costs, and how an agent collects the result of an async job.

The [Importly MCP server](/docs/integrations/mcp.md) exposes 10 tools. Five start paid jobs, four check on them for free, and one returns integration code without calling the API.

## How async jobs work

Downloads, transcripts, and metadata run as jobs. Each submit tool returns a `jobId` right away, along with a reminder to poll:

```text theme={null}
{
  "jobId": "95be812f-4a2c-410a-9fcb-3ca5b445cc44",
  "status": "queued",
  "message": "Transcription has been queued for processing."
}

Next step: poll check_transcription with jobId "95be812f-4a2c-410a-9fcb-3ca5b445cc44" every ~5 seconds. Most jobs finish in 10-60 seconds; long videos can take a few minutes.
```

The agent then calls the matching check tool until `status` is `completed` or `failed`. Check tools are free.

| Submit tool | Check tool | REST equivalent |
| - | - | - |
| `import_media` | `check_import` | [`POST /import`](/docs/endpoints/import) |
| `transcribe_media` | `check_transcription` | [`POST /transcribe`](/docs/endpoints/transcribe) |
| `get_metadata` | `check_metadata` | [`POST /metadata`](/docs/endpoints/metadata) |
| `get_basic_metadata` | `check_basic_metadata` | [`POST /metadata/basic`](/docs/endpoints/basic-metadata) |

## import\_media

Downloads the video or audio at a URL to hosted storage and returns a direct download link. Costs $0.01 per MB downloaded, with a $0.03 minimum, charged only when the download succeeds.

| Input | Type | Notes |
| - | - | - |
| `url` | string, required | Media page URL |
| `includeVideo` | boolean | Default `true`. `false` for audio only |
| `includeAudio` | boolean | Default `true` |
| `videoQuality` | string | `lowest`, `144p` … `2160p`, or `best`. Default `720p` |
| `audioQuality` | string | `lowest`, `low`, `medium`, `high`, or `best`. Default `medium` |
| `includeTranscript` | boolean | Also transcribe in the same job, billed as a transcript |
| `transcriptLanguage` | string | Language hint for the transcript, e.g. `en` |

`check_import` returns `mediaUrl` (valid for 7 days), `title`, `duration`, `fileSizeBytes`, `downloadedBytes`, `costInDollars`, and the `transcript` if you asked for one. See [Download media](/docs/features/downloads.md).

## transcribe\_media

Returns the transcript text and timestamped segments.

| Input | Type | Notes |
| - | - | - |
| `url` | string, required | Media page URL |
| `language` | string | Language hint, e.g. `en` |
| `provider` | `"importly"` | AI speech-to-text, for media without captions |
| `maxCostDollars` | number | Fail with a quote instead of running if the estimate is higher |

Without `provider`, it uses the video's captions for $0.01. If there are none, the job fails at no charge with a `TRANSCRIPTION_PROVIDER_REQUIRED` quote, and the agent can retry with `provider: "importly"` ($0.02 per minute, \$0.03 minimum, plus the audio download). Failed transcriptions are refunded. See [Transcripts](/docs/features/transcripts.md).

> [!NOTE]
>
> Your own AssemblyAI, Deepgram, or OpenAI key works through the REST API (`provider` plus `apiKey`), not through the MCP tool.

## get\_metadata

Full metadata without downloading: title, description, duration, uploader, formats, thumbnails, and view counts. \$0.01. Input: `url`. See [Metadata](/docs/features/metadata.md).

## get\_basic\_metadata

Title, duration, and thumbnail only. Faster than `get_metadata`, and useful to check a URL before importing or transcribing it. \$0.01. Input: `url`.

## check\_balance

Returns the remaining credit, for example `Importly credit balance: $2.97 USD`. Free. No inputs. Agents use it to explain a failed job or check before a large import.

## get\_integration\_guide

Returns working code for adding Importly to your own app: API key setup, starting a job, receiving the result by webhook or polling, and error handling. It doesn't call the API and uses no credits.

| Input | Values | Default |
| - | - | - |
| `language` | `node`, `nextjs`, `python`, `curl` | `node` |
| `useCase` | `import`, `transcribe`, `metadata` | `import` |

See [Build with your agent](/docs/integrations/build-with-your-agent.md).

## Errors

When a call fails, the tool returns an error that says what went wrong and what to do next:

| Error | What the agent should do |
| - | - |
| The API key was rejected | Check the `Authorization: Bearer <key>` header in the MCP config |
| Insufficient credits | Call `check_balance` and ask you to add credits |
| Rate limit reached | Wait a minute and retry |
| Job `failed` with a `code` such as `VIDEO_PRIVATE` | Tell you the media can't be fetched. See [supported sites](/docs/features/supported-sites.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.