Narrivela MCP setup: OAuth, clients, and speech tools

Create voiceovers through MCP

Connect your AI client to Narrivela, sign in with your Narrivela account, and generate speech from one script or a batch. The service handles long scripts, task progress, and MP3, WAV, or ZIP downloads. Start with the server address below, then follow the instructions for your client.

Try the web studio if you prefer to work in a browser.

Server details

Name: Narrivela
Server URL: https://app.narrivela.com/mcp
Transport: HTTPS Streamable HTTP. Select HTTP in your client.
Sign-in: Browser OAuth with your Narrivela account; verify your email before using the tools. No speech-provider API key is needed.
Input limits: Up to 50,000 UTF-16 code units across one job and 1,000 items; check the current limits with get_service_capabilities.

Sign in and start

Add the server
Create a remote HTTP MCP connection named Narrivela using https://app.narrivela.com/mcp.
Authorize your account
Follow the browser sign-in prompt and verify your email. The client should complete OAuth with PKCE and keep its registration and tokens for later sessions.
Try one short script
Ask your assistant to list Narrivela voices, generate a short narration, and return the download link. Then use the same task for longer scripts or batches.

Keep the connection in your client so you can return to it later. If authorization cannot start, see connection help.

Choose your client

These are setup paths for clients that support remote HTTP MCP and browser OAuth. Their menus and authentication behavior can vary by version. Use the connection checklist if a step differs in your client.

Codex: CLI setup
ChatGPT: Custom MCP connection
WorkBuddy: Custom remote connector
Claude Web / Desktop: Custom web connector
Cursor: Remote MCP URL
VS Code / Copilot: HTTP MCP server
Gemini CLI: HTTP MCP server
Dify: MCP tools
n8n: MCP Client

WorkBuddy

In connector management, add a custom remote connector named Narrivela using:

{
  "mcpServers": {
    "narrivela": {
      "type": "streamableHttp",
      "url": "https://app.narrivela.com/mcp",
      "timeout": 30000
    }
  }
}

Complete browser authorization with your Narrivela account. Keep the client configuration so later sessions reuse its registration. WorkBuddy connector guide.

Claude Web / Desktop

Add a remote connector
Open Customize → Connectors → Add → Custom → Web. Use Narrivela as the name and the server URL below.
Choose automatic registration
In OAuth client settings, choose Register automatically.
Authorize and check the tools
Complete browser authorization, then check the actual tool list and a task workflow. Team or Enterprise administrators may need to enable custom connectors.

https://app.narrivela.com/mcp

Claude connector guide.

Cursor

Add the remote URL in the project's .cursor/mcp.json or the global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "narrivela": {
      "url": "https://app.narrivela.com/mcp"
    }
  }
}

Start the connection and complete browser authorization. Cursor Desktop and Cursor Web may use different OAuth callbacks; let each client register its own connection. Cursor MCP guide.

VS Code / Copilot

Run MCP: Add Server from the command palette, choose HTTP, and enter the server URL. Alternatively, use .vscode/mcp.json:

{
  "servers": {
    "narrivela": {
      "type": "http",
      "url": "https://app.narrivela.com/mcp"
    }
  }
}

Start and trust the server, complete browser authorization, then enable Narrivela tools in chat. Workspace policy can restrict custom servers. VS Code MCP setup guide.

Gemini CLI

Add the HTTP server:

gemini mcp add --transport http narrivela https://app.narrivela.com/mcp

Or add this entry to .gemini/settings.json:

{
  "mcpServers": {
    "narrivela": {
      "httpUrl": "https://app.narrivela.com/mcp"
    }
  }
}

Run /mcp auth narrivela in Gemini CLI and complete browser authorization. Gemini CLI MCP guide.

Dify

Open Integrations → Tools → MCP and add these values:

Name: Narrivela
Server URL: https://app.narrivela.com/mcp
Server identifier: narrivela
Dynamic Client Registration: Keep enabled, then complete Narrivela account authorization.

Import Narrivela tools into your workflow and keep the server identifier stable. Calls use the Narrivela account authorized by the workspace; visitors to the workflow do not automatically get separate accounts or credit. Dify Tools guide.

n8n

Use MCP Client for workflow steps, or MCP Client Tool with an AI Agent. Configure:

Transport: Streamable HTTP, when the installed node version provides it.
MCP Endpoint: https://app.narrivela.com/mcp
Authentication: MCP OAuth2 credential
Use Dynamic Client Registration: Keep enabled.
Resource URL: https://app.narrivela.com/mcp, or discover it automatically.
OAuth Redirect URL: Use the exact URL shown by that n8n credential.

Complete browser authorization, then choose a Narrivela tool. Use a node version that supports HTTP MCP and OAuth2. Workflows using the same credential share its Narrivela account, tasks, and credit. Poll an existing task rather than submitting generation again on each loop. n8n MCP credential guide.

Speech tools

Narrivela works through standard MCP tool results. Your client can follow task progress and open the returned HTTPS download links without a special audio player.

Discover limits and voices: get_service_capabilities supplies input and attachment boundaries. list_voices supplies actual voices and model/language restrictions.
Check your allowance: get_account_usage returns the current account's allowance, limits, and own tasks.
One complete passage: text_to_speech accepts complete text and returns a background job_id. The server splits and joins text within its input limits.
Ordered passages: batch_text_to_speech accepts items: [{id,text}]. Keep item IDs unique and preserve the intended order.
Progress and pages: get_speech_job accepts job_id, offset, and limit. Follow next_offset until it is null to retrieve all items.
Stop or resume: cancel_speech_job and resume_speech_job operate on owned tasks. Resume can consume more allowance; prior provider attempts remain charged.

Submit once, then follow the task

Prepare complete input
Read an authorized text file in your client, or extract document text there. Check current service limits, voices, and your allowance. A language hint does not translate your script.
Submit one task
Use text_to_speech for one passage or batch_text_to_speech for ordered passages. Save the returned job_id. Acceptance or queuing is not completion.
Query that job at spaced intervals
Use get_speech_job, respect retry_at when present, and stop polling when status is completed, failed, or cancelled. Read errors before deliberately resuming. Do not call generation again just to check progress.
Retrieve every result page
Use next_offset as the next offset until it is null. Download completed items and the complete manifest or ZIP.

Example text_to_speech parameters:

{
  "text": "Welcome to Narrivela.",
  "language": "en",
  "output_format": "wav"
}

Example batch_text_to_speech parameters:

{
  "items": [
    {
      "id": "intro",
      "text": "Welcome to Narrivela."
    },
    {
      "id": "ending",
      "text": "Thank you for listening."
    }
  ],
  "language": "en",
  "output_format": "wav"
}

For get_speech_job, replace the placeholder with the returned job ID. Start at offset 0 and follow next_offset to retrieve the remaining results:

{
  "job_id": "ACTUAL_RETURNED_JOB_ID",
  "offset": 0,
  "limit": 100
}

Check current input and concurrency limits with get_service_capabilities. Narrivela supports ordinary narration; style prompts are not available in this release.

Audio, ZIP, and manifest links

Completed items provide audio_url for playback and audio_download_url for downloading. A completed job provides bundle_url for all audio and a manifest in a ZIP, and manifest_url for the complete JSON manifest. These are HTTPS links; your client may also show an embedded player.

Completed audio is normally available for about 24 hours. Download it before the expires_at time shown on your task. Keep the returned links private: anyone holding a valid signed link can retrieve the result. A link's exp is its access expiry and can be earlier than file expiry. While your task is retained, sign in and check it again to get a fresh link.

Files and optional displays

For text or JSONL files, have your client read the file and send the text or ordered {id,text} items. A remote MCP server cannot open a path on your computer. For a larger file, use the web studio within its displayed limits.

show_speech_job can display a progress and download card in clients that support it. get_speech_job and its download links work without the card. Direct file, visual, or video attachments require that client's supported attachment reference; openai/fileParams is an OpenAI-specific example.

Account use and credit

Tools operate on the authorized Narrivela account's own tasks. The new-user plan grants a one-time non-cash credit of CNY 10; it does not renew. All accounts also share the service budget of CNY 1,000 per UTC calendar month, alongside input, concurrency, and active-task limits. Read current credit availability and cost rules.

Shared workflows in Dify or n8n use the Narrivela identity attached to their credential. Their visitors do not each receive a new Narrivela allowance. Calls authorized by the same credential also share that account's task-access permissions; Narrivela does not independently separate those workflow visitors into distinct task owners. Keep credentials and result links private; never embed an operator's provider key in a workflow.

Find Narrivela

Narrivela is listed in the MCP Registry as com.narrivela/narrivela, version 0.6.0. You can view the Registry record or connect directly using the server URL above.

If registration is unavailable

Some clients need a new OAuth registration on first connection. If your client reports a registration limit, keep an existing working connection and contact support with the client name and error. You can use the web studio while the new connection is unavailable.

When a connection fails

Check that the client uses HTTP MCP and supports browser OAuth. Confirm your email is verified and that the callback URL shown by the client is accepted. If registration capacity blocks a new connection, keep any working configuration and contact support; the web studio remains available. Include your client version, time, and error code when asking for help. Keep passwords, tokens, signed download URLs, and private scripts out of support messages.