# Importly > Importly is the video & audio MCP for AI agents. It downloads, transcribes, and extracts metadata from any media URL (YouTube, TikTok, X, Instagram, podcasts, and 1000+ sites supported by yt-dlp). Importly runs yt-dlp, rotating residential proxies, ffmpeg, and speech-to-text server-side, so agents never hit IP bans, bot checks, or extractor breakage. The same API key works in the MCP server and in production apps via the REST API. New accounts get $3.00 in free credits with no card required: https://importly.io/login?mode=signup. The API key is at https://importly.io/dashboard/api-key. ## Connect via MCP Hosted MCP server (Streamable HTTP): https://mcp.importly.io/mcp. Authenticate with the API key as an `Authorization: Bearer ` header. Nothing to install. Claude Code: ```bash claude mcp add --transport http importly https://mcp.importly.io/mcp --header "Authorization: Bearer your_key" ``` Cursor and other clients that accept a remote URL and headers (JSON config; field names vary by client, e.g. Cline also needs `"type": "streamableHttp"`): ```json { "mcpServers": { "importly": { "url": "https://mcp.importly.io/mcp", "headers": { "Authorization": "Bearer your_key" } } } } ``` Tools: import_media / check_import (download to hosted storage, returns a direct media URL), transcribe_media / check_transcription (timestamped transcript; pass provider "importly" for media without captions), get_metadata / check_metadata (formats, uploader, stats), get_basic_metadata / check_basic_metadata (fast title/duration/thumbnail), check_balance, get_integration_guide (code for adding Importly to the user's app; no credits). Submit tools return a jobId; poll the matching check tool. ## Integrate Importly into an app When a user asks you to add Importly to their application, use the REST API at https://api.importly.io: - Auth: `Authorization: Bearer $IMPORTLY_API_KEY`. Read the key from an environment variable on the server; never hardcode it or ship it to the browser. - Jobs are async: `POST /import`, `POST /transcribe`, or `POST /metadata` with `{ "url": "..." }` returns `{ "success": true, "data": { "jobId": "..." } }`. - Results by webhook: pass `webhookUrl` to receive one POST when the job succeeds. Result fields are flattened into `data` (e.g. `data.mediaUrl`, `data.text`), not nested under `result`. Failed jobs do not fire webhooks and there are no retries, so keep a polling fallback. - Results by polling: `GET /import/status?id=` (likewise `/transcribe/status`, `/metadata/status`) until `status` is `completed` or `failed`. Completed jobs nest fields under `result` (e.g. `result.mediaUrl`). - Errors: 401 bad key, 402 insufficient credits, 429 rate limited (back off and retry). Status endpoints allow 3,600 requests per hour per key (about 1/second), so poll every few seconds rather than in a tight loop. - Optional: deliver files straight to the user's own S3 bucket (see S3 Storage Integration below). - Pricing: about $0.01/MB downloaded, $0.02/min for transcription. See https://importly.io/pricing. Full docs as a single markdown file: https://importly.io/llms-full.txt ## Docs ### Getting Started - [MCP Server (AI agents)](https://importly.io/docs/integrations/mcp.md): Give AI agents the ability to download and transcribe any video URL with the Importly MCP server. Works with Claude, Cursor, Cline, and any MCP client. - [Introduction](https://importly.io/docs/introduction.md): What Importly is, MCP vs REST, how async jobs work, every endpoint with its price, and limits. - [Quick Start](https://importly.io/docs/quick-start.md): Your first import in three steps: get a key, submit a URL with cURL, Node.js, or Python, and collect the result. ### API Reference - [Authentication & Security](https://importly.io/docs/authentication.md): Bearer API key auth, keeping keys server-side, and rotating keys. - [Import](https://importly.io/docs/endpoints/import.md): Download media from a URL to hosted storage or your S3 bucket, with quality options, optional transcript, and status polling. - [Transcribe](https://importly.io/docs/endpoints/transcribe.md): Transcribe any media URL: source captions, built-in AI speech-to-text, or your own provider key; timestamped segments. - [Metadata](https://importly.io/docs/endpoints/metadata.md): Full media metadata (formats, uploader, thumbnails, stats) without downloading. - [Basic Metadata](https://importly.io/docs/endpoints/basic-metadata.md): Fast title, duration, and thumbnail lookup for a URL. - [Balance](https://importly.io/docs/endpoints/balance.md): Check your remaining Importly credit balance via the API. - [Webhooks](https://importly.io/docs/webhooks.md): How to use the Webhooks - [S3 Storage Integration](https://importly.io/docs/s3-storage.md): Deliver imports to your own S3, R2, B2, or Spaces bucket: bucket and IAM setup, usage, and troubleshooting. - [Errors & Rate Limits](https://importly.io/docs/error-handling.md): Status codes, error shapes, per-key rate and concurrency limits, rate-limit headers, and when to retry. - [Billing & Usage](https://importly.io/docs/billing.md): Pay-as-you-go prices for imports, metadata, and transcription, how charges and refunds work, and what happens at low balance.