# Happy Scribe — how to use (mcp.ai)

Connect your Happy Scribe account and use 20 tools for transcription straight from your AI agent. Connect with your own API key. Happy Scribe offers automatic and professional transcription services, converting audio and video files into text with high accuracy.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_happy_scribe?ms=1787291280000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `happy_scribe_create_subtitle`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/happy_scribe`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/happy_scribe/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/happy_scribe/create/subtitle` — Create subtitles for a video file using Happy Scribe's automatic transcription service. Submits a video URL to be processed for subtitle generation. The video must be publicly accessible during ingest
  - body: { transcription: object }
- `POST https://api.mcp.ai/api/happy_scribe/create/translation/task` — Creates an AI-powered translation task to translate an existing transcription into another language. Use this after a transcription is complete (state='automatic_done') to translate it. The task runs 
  - body: { target_language: string, source_transcription_id: string }
- `POST https://api.mcp.ai/api/happy_scribe/delete/transcription` — Tool to delete a transcription job. Use when you have a transcription ID and want to remove it, optionally permanently. Use after confirming the transcription ID.
  - body: { id: string, permanent?: boolean }
- `POST https://api.mcp.ai/api/happy_scribe/delete/webhook` — Deletes a webhook by its ID. This action is idempotent: if the webhook does not exist or was already deleted, it returns success. Use Get Webhooks to retrieve available webhook IDs.
  - body: { id: string }
- `POST https://api.mcp.ai/api/happy_scribe/get/account/details` — Tool to retrieve details about your account, including subscription status and usage statistics. Use after authenticating your API key to monitor plan and usage.
  - body: { organization_id?: string }
- `POST https://api.mcp.ai/api/happy_scribe/get/language/list` — Retrieve the list of supported language codes for Happy Scribe transcription services. Returns BCP-47 language codes and indicates which languages have human transcription service available. This is a
  - body: { filter_human_service?: boolean }
- `POST https://api.mcp.ai/api/happy_scribe/get/rate/limit` — Get Happy Scribe API rate limit information. Returns the documented rate limit for the Happy Scribe API: - Default limit: 200 requests per hour - Applies only to the transcription creation endpoint - 
- `POST https://api.mcp.ai/api/happy_scribe/get/signed/upload/url` — Tool to get a signed URL for uploading a file to Happy Scribe's S3 storage. Use before creating a transcription or order to obtain a secure upload URL for your media file.
  - body: { filename: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/confirm/order` — Tool to confirm a pending order. Use after creating an order with confirm=false when you're ready to submit it for processing.
  - body: { id: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/create/translation/order` — Tool to create a translation order from an existing transcription. Use when you have a completed transcription and want translations into one or more languages. By default, the order remains incomplet
  - body: { order: object }
- `POST https://api.mcp.ai/api/happy_scribe/hs/export/transcription` — Creates an export job to download transcription content in various formats. Use this action after a transcription job completes (state='automatic_done'). First obtain transcription IDs using the List 
  - body: { format: string, showComments?: boolean, showSpeakers?: boolean, showHighlights?: boolean, showTimestamps?: boolean, transcriptionIds: string[], showHighlightsOnly?: boolean, timestampsFrequency?: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/get/api/version` — Tool to retrieve current API version and check for updates. If Happy Scribe does not expose a dedicated /version endpoint, this tool attempts to infer the version from HTTP response headers or from th
  - body: { organization_id?: string, endpoint_preference?: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/get/error/codes` — Returns a list of HTTP error codes used by the Happy Scribe API along with their descriptions. Use this tool to understand what different error responses mean when calling other Happy Scribe API endpo
- `POST https://api.mcp.ai/api/happy_scribe/hs/get/supported/formats` — Tool to retrieve supported file formats. Use when you need to know available input and output formats before creating a transcription or subtitle. If a dedicated '/formats' endpoint is unavailable, th
  - body: { limit?: integer, test_note?: string, include_audio?: boolean, include_video?: boolean, export_category?: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/get/transcription` — Tool to retrieve details and status of a specific transcription job. Use after creating or listing transcription jobs to inspect a particular job's metadata.
  - body: { id: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/get/webhooks` — Tool to retrieve webhooks configured for your account. Note: Happy Scribe's public API does not have a dedicated webhooks listing endpoint. Webhooks are specified via webhook_url when creating orders.
  - body: { organization_id?: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/retrieve/export` — Tool to retrieve information about a specific export. Use when you need to check export status and get download link.
  - body: { id: string }
- `POST https://api.mcp.ai/api/happy_scribe/hs/retrieve/translation/task` — Retrieves the status and details of a translation task by its ID. Use this after creating a translation task with HAPPY_SCRIBE_CREATE_TRANSLATION_TASK to check progress (state: initial, working, faile
  - body: { id: string }
- `POST https://api.mcp.ai/api/happy_scribe/list/transcriptions` — Retrieves a paginated list of transcription jobs for a Happy Scribe organization. Returns transcription metadata including ID, name, processing state, language, and duration. Supports filtering by fol
  - body: { page?: integer, tags?: string[], folder_id?: string, organization_id: string }
- `POST https://api.mcp.ai/api/happy_scribe/retrieve/order` — Retrieve details of a Happy Scribe order by its ID. Returns order state, pricing, operations, and inputs. Use this to check order status, verify pricing details, or get information about translation/t
  - body: { id: string }

## Example prompts
- "What can I do in Happy Scribe?"
- "Show me a summary of my Happy Scribe account"

## More
- Page: https://mcp.ai/happy_scribe
- Agent spec (llms.txt): https://mcp.ai/happy_scribe/llms.txt
- Postman collection: https://mcp.ai/happy_scribe/postman.json