AssemblyAI

AssemblyAI MCP サーバー

AssemblyAI API 用のリモート MCP サーバーです。MCP 対応エージェント向けに、非同期の音声テキスト変換、Speech Understanding（翻訳、話者識別、カスタム形式、章立て要約、アクション項目）、Guardrails（PII の編集、コンテンツモデレーション、冒とく表現のフィルタリング）をカバーする 5 つのツールを提供します。Streamable HTTP 経由で提供され、リクエストごとに認証されます。認証方法は、AssemblyAI にサインインする（OAuth）か、呼び出し元自身の AssemblyAI API キーを使用するかのいずれかです。

MCP の認可に対応する MCP クライアント（Claude Code、Claude.ai、Cursor、MCP Inspector など）、または Bearer ヘッダーを送信できるクライアントで利用できます。Next.js 16、mcp-handler、公式の @modelcontextprotocol/sdk を使用して構築されており、Vercel のサーバーレス関数としてデプロイされます。

クイックスタート

AssemblyAI にサインインする場合： ヘッダーなしで、サーバーの /mcp エンドポイントを追加します。クライアントで AssemblyAI のサインインと同意のページが開き、サーバーはその接続用に取得した API キーを使用します。コピーや貼り付けは不要です。（AssemblyAI のホスト型デプロイに対して動作します。セルフホストしたコピーでは API キーを使用します。認証を参照してください。）

claude mcp add --transport http assemblyai https://<host>/mcp

API キーを使用する場合： AssemblyAI API キーを Bearer トークンとして指定し、MCP クライアントから /mcp エンドポイントに接続します。

Claude Code

claude mcp add --transport http assemblyai https://<host>/mcp \
  --header "Authorization: Bearer $ASSEMBLYAI_API_KEY"

汎用リモート MCP クライアントの設定

{
  "mcpServers": {
    "assemblyai": {
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <ASSEMBLYAI_API_KEY>" }
    }
  }
}

ホスト型インスタンスがすぐに使えない場合は、npm install && npm run dev を実行すると、http://localhost:3000/mcp で利用できます（ローカル開発を参照してください）。

次に、エージェントにプロンプトを入力します。例：*「この音声ファイルを書き起こして、要約してください：https://assembly.ai/wildfires.mp3」*。

ツール

ツール	用途
submit_transcript(audio_url, ...)	公開されている音声／動画 URL の非同期書き起こしを開始します。すぐに { transcript_id, status } を返します。
get_transcript(transcript_id)	現在の状態を取得します。status が completed になると、完全な結果を取得できます。エージェントは約 3 秒ごとにポーリングします。
understand_transcript(transcript_id, speech_understanding)	完了済みのトランスクリプトに対して、音声を再送信せずに Speech Understanding を実行します。翻訳、話者識別、カスタム形式、章立て要約、アクション項目に対応します（LLM Gateway /v1/understanding）。
summarize_transcript(transcript_id, style?, custom_prompt?)	LLM Gateway を通じて、完了済みのトランスクリプトを自由形式またはカスタムプロンプトで要約します。style：bullets（デフォルト）、paragraph、headline、action_items、または custom。
delete_transcript(transcript_id)	トランスクリプトとそのデータを完全に削除します。取り消しできません。ユーザーから明示的に依頼された場合にのみ実行してください。

エージェントの一般的なフロー： submit_transcript → completed になるまで get_transcript をポーリング → 必要に応じて understand_transcript / summarize_transcript を実行 → ユーザーからクリーンアップを依頼されたら delete_transcript を実行します。必要な機能が事前に分かっている場合は、後から追加するのではなく、送信時に Speech Understanding の機能を指定してください。

submit_transcript のパラメーター一覧

API ネイティブの名前を使い、公開されている非同期文字起こしのパラメーター一式を受け付けます。おおまかに次のように分類されています。

• プロンプト — prompt（音声の文脈を説明するものであり、指示ではありません）、keyterms_prompt
• 言語 — language_code、language_codes、language_detection、language_detection_options、language_confidence_threshold
• モデル — speech_models（デフォルトでは固定された優先順位リスト ["universal-3-5-pro", "universal-2"] を使用）、temperature
• 話者分離 — speaker_labels、speaker_options
• ガードレール — redact_pii（および redact_pii_policies、redact_pii_sub、redact_pii_audio、redact_pii_return_unredacted、redact_static_entities）、filter_profanity、content_safety（および content_safety_confidence）、speech_threshold
• 音声理解（インライン） — speech_understanding.request.{translation, speaker_identification, custom_formatting, summarization, action_items}。文字起こし中に実行されます。
• その他 — sentiment_analysis（英語のみ）、entity_detection、iab_categories、auto_highlights、multichannel、disfluencies、custom_spelling、punctuate、format_text、audio_start_from、audio_end_at、domain（医療モードでは medical-v1）、remove_audio_tags、および Webhook（webhook_url、webhook_auth_header_name／_value）

省略されたパラメーターは送信されず、AssemblyAI 独自のデフォルト値が適用されます。パラメーターの意味については、submit エンドポイントのドキュメントを参照してください。

get_transcript の出力

一部の MCP クライアントはモデルに content[].text のみを渡すため、すべての内容はラベル付きセクションとして content[].text に出力されます。--- text --- と --- utterances --- は常に含まれます。リクエストされている場合、または存在する場合は、センチメント、エンティティ、翻訳（文字起こし全体および発話ごと）、話者識別、カスタム書式、チャプター分けされた要約、アクションアイテム、コンテンツの安全性、トピック、ハイライト、未編集のテキスト、編集済み音声の URL、処理に関する警告も含まれます。生のフィールドは structuredContent にも複製されます。

認証

すべてのリクエストには Bearer トークンが含まれます。トークンは次のいずれかです。

OAuth アクセストークン（AssemblyAI でサインイン）。 トークンなしのリクエストには、WWW-Authenticate ヘッダーに /.well-known/oauth-protected-resource を示す 401 が返されます。このエンドポイントから AssemblyAI の認可サーバーが特定されます。クライアントはそこで自身を登録し、同意ページを通じてメンバーをサインインさせ（スコープ aai:api）、取得したアクセストークンを送信します。AssemblyAI の API が受け付けるのはアクセストークンではなく API キーです。そのため src/oauth.ts は、リクエストが withMcpAuth に到達する前に、トークンをクライアントに対するメンバーの接続用 API キーと交換します（POST /api/v2/oauth/api-key）。その後、リクエストはそのキーを使って続行されます。この交換処理では、リクエスト元のサーバーも検証します。デプロイ環境の Vercel OIDC トークンが X-AAI-Service-Token に渡され、AssemblyAI はこのプロジェクトの本番デプロイのみを受け付けるため、セルフホストしたコピーではトークンを交換できず、代わりに API キーを使用します。キーはアクセストークンごとに最大 5 分間キャッシュされるため、ダッシュボードから接続を取り消すと、数分以内に使えなくなります。拒否されたトークンには 401（スコープが不足している場合は 403）が返され、クライアントはサインインに戻されます。一方、停止中の場合に返されるのは 503 であり、サインインには戻されません。

AssemblyAI API キー（そのまま渡す方式）。 MCP クライアントは API キーを Authorization: Bearer <key> として送信します（ほとんどのクライアント設定では Bearer が自動的に付加されます）。AssemblyAI の REST API はキーそのものを必要とするため、withMcpAuth はトークンを取り出してプレフィックスを除去し、extra.authInfo.token を介してすべてのツールコールバックに渡します。キーがディスクに書き込まれたり、リクエスト間で共有されたりすることはありません。各リクエストは、受け取ったキーを使って処理されます。

設定

すべての設定はデフォルトで AssemblyAI の本番エンドポイントを使用するため、本番環境へのデプロイでは設定は不要です。別の AssemblyAI 環境に対してサインインするデプロイでは、その環境のキーはその環境の API でのみ機能するため、4 つすべてをまとめて設定します。

変数	デフォルト	内容
ASSEMBLYAI_OAUTH_ISSUER	https://auth.assemblyai.com	保護されたリソースのメタデータに示される認可サーバー
ASSEMBLYAI_OAUTH_EXCHANGE_ORIGIN	https://www.assemblyai.com	アクセストークンを API キーに交換する先
ASSEMBLYAI_BASE_URL	https://api.assemblyai.com	AssemblyAI API
ASSEMBLYAI_LLM_GATEWAY_BASE_URL	https://llm-gateway.assemblyai.com	LLM Gateway

サービスのトークンに設定は不要です。Vercel がデプロイに提供し（VERCEL_OIDC_TOKEN）、@vercel/oidc が読み取ります。

ツールの拡張（追加のみの契約）

MCP クライアントは実行時にツールを検出します（list_tools）。クライアント設定に保存されるのは URL と認証情報のみで、ツールスキーマのスナップショットは保存されません。そのため、新しいツールや新しい任意のパラメーターは自動的に反映されます。クライアントの再設定は不要で、接続テストの手順があるプラットフォームでも、再テストは不要です。この保証を維持するため、ここでの変更はすべて追加のみとします。

1. ツール名は固定です — ツールの追加のみとし、名前の変更や削除は行いません。
2. 新しい入力は常に任意です。現在の動作を維持するデフォルト値を設定します。
3. get_transcript のテキスト出力には、ラベル付きセクションを追加するだけです — 既存のセクション（--- text ---、--- utterances ---、--- sentiment ---、--- entities ---）の名前や形式は変更しません。テキストのみを扱う MCP クライアントは content[].text を読み取るためです。（旧形式の --- summary --- セクションが存在する場合は引き続き出力されますが、現在、要約は get_transcript ではなく summarize_transcript ツールから取得します。）同じ保護は、Speech Understanding およびガードレール向けに追加された新しいセクションにも適用されます。--- translation:<lang> ---、--- translated_utterances ---、--- speaker_identification ---、--- custom_formatting ---、--- su_summary ---、--- action_items ---、--- content_safety ---、--- topics ---、--- highlights ---、--- unredacted_text ---、--- redacted_audio ---、--- warnings ---。
4. structuredContent は追加のみです — フィールドは追加しますが、削除や名前の変更はしません。
5. 非推奨の AssemblyAI トランスクリプトパラメーター（auto_chapters、summarization、summary_model、summary_type）は使用せず、代わりに LLM Gateway を使用します。公式の AssemblyAI MCP ツールの形式が存在する場合は、それに準拠します。

ローカル開発

Node 24.x が必要です。

npm install
npm test                # in-process smoke + OAuth exchange tests (no network)
npm run dev             # next dev on http://localhost:3000

MCP エンドポイント：http://localhost:3000/mcp。OAuth 保護リソースのメタデータ：http://localhost:3000/.well-known/oauth-protected-resource。 サインインには AssemblyAI が受け入れるデプロイが必要です（認証を参照）。ローカルでは API キーを使用してください。

MCP Inspector でのスモークテスト

npx @modelcontextprotocol/inspector

Streamable HTTP 経由で http://localhost:3000/mcp に接続し、AssemblyAI キーを Bearer トークンとして貼り付けます。公開 mp3 URL を使って submit_transcript を呼び出し、返された ID を指定して、完了するまで get_transcript を呼び出します。

curl でのスモークテスト

# No auth — expect 401
curl -i -X POST http://localhost:3000/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# With your AssemblyAI key as the Bearer token — expect 200 + Mcp-Session-Id
curl -i -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $ASSEMBLYAI_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

ライブのエンドツーエンドテスト（実際の AssemblyAI、実際の文字起こし）

ASSEMBLYAI_API_KEY=... npm run test:live                       # against localhost:3001
ASSEMBLYAI_API_KEY=... MCP_URL=https://<host>/mcp npm run test:live

Streamable HTTP 経由で MCP SDK クライアントを使い、実行中のサーバーを操作します。ツールの検出、submit_transcript のすべての機能フラグ、speech_model_used のアサーション、summarize_transcript、インラインの Speech Understanding（翻訳＋章立てされた要約）、ガードレール（コンテンツセーフティ）、understand_transcript による事後の Speech Understanding、不正な音声 URL での正常なエラー処理、delete_transcript による後処理をテストします。submit_transcript が返すとすぐに各トランスクリプト ID を記録し、finally ブロックで削除するため、実行が途中で失敗した場合も、正常に作成できたすべてのトランスクリプトをスイートが後処理します。1 回の実行につき、文字起こしクレジットが数セント分必要です。

デプロイへのサインインテスト

MCP_URL=https://<deployment>/mcp VERCEL_PROTECTION_BYPASS=<secret> npm run test:oauth

MCP クライアントと同じ方法でサインインし、デプロイからすべての情報を検出します。401 チャレンジ、保護されたリソースのメタデータ、認可サーバーのメタデータ、クライアント登録を確認し、続いてブラウザーの同意ページで PKCE を実行します（「Allow」をクリックしてください）。その後、ツールを一覧表示し、アクセストークンを使ってツールを 1 回呼び出し、改ざんされたトークンが拒否されることを確認します。 VERCEL_PROTECTION_BYPASS は、Vercel Authentication で保護されたプレビューデプロイ向けの、デプロイの Protection Bypass for Automation シークレットです。 API キーは不要で、文字起こしのクレジットも消費しません。

プロジェクト構成

assemblyai-mcp/
├── app/
│   ├── mcp/[[...path]]/route.ts             # mcp-handler entry, wrapped with withOAuthExchange + withMcpAuth
│   └── .well-known/oauth-protected-resource/route.ts
├── src/
│   ├── server.ts                            # registerTools factory
│   ├── oauth.ts                             # Sign in with AssemblyAI: access token → API key exchange
│   ├── log.ts                               # JSON logging helpers + key hashing
│   ├── tool-errors.ts                       # shared 401/404/429 error mapper
│   ├── assemblyai.ts                        # fetch wrapper (submit, get, delete, retry)
│   ├── llm-gateway.ts                       # LLM Gateway client (summarize, understand)
│   ├── transcript-sections.ts               # section renderers for tool text output
│   ├── speech-understanding-schema.ts       # shared speech_understanding zod schema
│   ├── tools/
│   │   ├── submit-transcript.ts
│   │   ├── get-transcript.ts
│   │   ├── summarize-transcript.ts
│   │   ├── understand-transcript.ts
│   │   └── delete-transcript.ts
│   ├── smoke-test.ts                        # InMemoryTransport, mocked fetch
│   ├── oauth-test.ts                        # token exchange, stubbed (npm test)
│   ├── oauth-preview-test.ts                # sign-in against a deployment (npm run test:oauth)
│   └── live-test.ts                         # real API, Streamable HTTP client
├── package.json
├── tsconfig.json
├── next.config.js
├── vercel.json
└── README.md

ログ

AssemblyAI のドキュメント MCP サーバーと同じパターンで、JSON を標準出力に出力します。各ツールは、event、tool、keyHash、latencyMs、status を含むイベントを 1 つ出力します。アラート対象として重要度の高いイベントは、bad_audio_url、assemblyai_rejected_key、tool_error、understanding_error、delete_error です。生の API キーはログに記録せず、sha256(key).slice(0,12) のみを記録します。また、文字起こしの内容もログに記録しません。

デプロイ

Vercel にデプロイします（プロジェクトをリンクした後、vercel deploy を実行します）。Vercel Firewall がレート制限と DDoS 保護を提供します。MCP エンドポイントは https://<host>/mcp にあり、ハンドラーの設定に従って maxDuration: 60 となります。

参考：以前の Python 実装

この TypeScript ポートに先立つ、Python の FastMCP ベースの実装は、このリポジトリの最初のコミット（git log --reverse --oneline | head -1）に保存されています。この実装は設計（認証ブリッジ、エラー処理、レスポンスの形式）の信頼できる情報源となっており、この TypeScript ポートではその設計をサーバーレスに適したプラットフォームへ引き継いでいます。