Skip to main content

​
Overview

The Voice File tools provide read-only access to voice file processing status, transcripts, and translations. All tools in this group require the mcp:voice:read scope. Available Tools:
  • get_voice_file_job - Check the processing status of a voice file
  • get_voice_file_transcript - Retrieve the transcript of a processed voice file
  • get_voice_file_translations - Get all available translations
  • get_voice_file_translation - Get a translation in a specific language
Primary Use Cases:
  • Monitor voice file processing progress
  • Retrieve transcripts after processing completes
  • Access translations in multiple languages

​
get_voice_file_job

Checks the current processing status of a voice file job. Required Scope: mcp:voice:read

​
Parameters

ParameterTypeRequiredDescription
jobIdstringYesThe unique job ID returned when the voice file was submitted

​
Request Example

{
  "jobId": "job_abc123def456"
}

​
Response

{
  "jobId": "job_abc123def456",
  "status": "completed",
  "progress": 100,
  "createdAt": "2026-03-26T10:00:00Z",
  "completedAt": "2026-03-26T10:05:30Z"
}
Field Descriptions:
FieldTypeDescription
jobIdstringThe unique job identifier
statusstringCurrent status: pending, processing, completed, or failed
progressnumberProcessing progress percentage (0-100)
createdAtstringTimestamp when the job was created (ISO 8601)
completedAtstring | nullTimestamp when processing finished (ISO 8601)
Processing time varies based on audio length and server load. Typically, a 1-hour audio file takes approximately 18 minutes to process (~0.3x real-time).

​
get_voice_file_transcript

Retrieves the full transcript of a processed voice file. Required Scope: mcp:voice:read

​
Parameters

ParameterTypeRequiredDescription
jobIdstringYesThe unique job ID

​
Request Example

{
  "jobId": "job_abc123def456"
}

​
Response

{
  "jobId": "job_abc123def456",
  "transcript": {
    "segments": [
      {
        "speaker": "Speaker 1",
        "startTime": 0.0,
        "endTime": 5.2,
        "text": "Good morning everyone, let's get started with today's agenda."
      },
      {
        "speaker": "Speaker 2",
        "startTime": 5.5,
        "endTime": 12.1,
        "text": "Sure. I wanted to discuss the Q2 roadmap first."
      }
    ],
    "locale": "en",
    "duration": 3600.0
  }
}
Field Descriptions:
FieldTypeDescription
segmentsarrayList of transcript segments
segments[].speakerstringSpeaker identifier
segments[].startTimenumberSegment start time in seconds
segments[].endTimenumberSegment end time in seconds
segments[].textstringTranscribed text for the segment
localestringDetected language code
durationnumberTotal audio duration in seconds
The transcript is only available after the job status is completed. Calling this tool on a pending or processing job will return an error.

​
get_voice_file_translations

Retrieves all available translations for a processed voice file. Required Scope: mcp:voice:read

​
Parameters

ParameterTypeRequiredDescription
jobIdstringYesThe unique job ID

​
Request Example

{
  "jobId": "job_abc123def456"
}

​
Response

{
  "jobId": "job_abc123def456",
  "translations": [
    {
      "locale": "en",
      "text": "Good morning everyone, let's get started..."
    },
    {
      "locale": "ja",
      "text": "皆さんおはようございます、始めましょう..."
    },
    {
      "locale": "ko",
      "text": "안녕하세요 여러분, 시작하겠습니다..."
    }
  ]
}
Field Descriptions:
FieldTypeDescription
translationsarrayList of available translations
translations[].localestringLanguage code (e.g., en, ja, ko)
translations[].textstringTranslated full text

​
get_voice_file_translation

Retrieves a translation in a specific language. Required Scope: mcp:voice:read

​
Parameters

ParameterTypeRequiredDescription
jobIdstringYesThe unique job ID
localestringYesTarget language code (e.g., en, ja, ko, zh)

​
Request Example

{
  "jobId": "job_abc123def456",
  "locale": "ja"
}

​
Response

{
  "jobId": "job_abc123def456",
  "locale": "ja",
  "text": "皆さんおはようございます、今日の議題を始めましょう。Q2のロードマップについて最初に議論したいと思います。"
}

​
Common Errors

​
Job Not Found

Solution: Verify the jobId is correct.

​
Job Not Completed

Solution: Wait for the job to complete. Use get_voice_file_job to check the current status.

​
Translation Not Available

Solution: Use get_voice_file_translations to see which languages are available.

​
Best Practices

Always call get_voice_file_job first to confirm the job status is completed before attempting to retrieve transcripts or translations. This avoids unnecessary error responses.
If you only need one language, use get_voice_file_translation with a specific locale instead of get_voice_file_translations. This returns a smaller payload and uses fewer tokens.
Voice file processing takes time (typically ~0.3x real-time). Build your workflow to poll get_voice_file_job periodically rather than waiting synchronously.

​
Next Steps

search_notes

Find notes associated with voice files

Tools Overview

Learn about all available MCP tools