Narrivela MCP setup: OAuth, clients, and speech tools

Connection and verification status

Production service protocol verified (SDK)

On October 14, 2026, MCP SDK 1.32.0 verified the live production protocol: public-client DCR, authorization code with S256 PKCE and no client secret, a signed access token with strict email verification, and one rotating refresh that preserved the same account.

Without a dedicated UI, the SDK read the live get_service_capabilities result and completed one batch of two short passages using Qwen Audio 3.0 TTS Plus. Both WAV downloads and the ZIP containing two audio files and a manifest were checked. This verifies the service protocol, not a connection in any of the seven host applications below. Long-text and large-batch support uses the same server implementation and isolated SDK fixtures; live production generation of large passages or large batches has not been verified.

First-time generic client registration is subject to Auth0 application capacity.

Documentation checked on October 14, 2026. None of the seven clients below is marked as passed. Check web speech and public plugin availability separately.

Server details

Name: Narrivela
Server URL: https://app.narrivela.com/mcp
Transport: HTTPS Streamable HTTP. Use this exact address; do not select local stdio or invent an SSE endpoint.
OAuth resource: https://app.narrivela.com/mcp
Scope: voxkit:use is the existing permission identifier. The product name is Narrivela.
Account: Sign in to a Narrivela account and verify its email before calling account tools. No speech-provider API key is required.
Current generic login status: Live SDK authorization code, S256 PKCE, strict email verification, and one rotating refresh passed. Authorization and tool workflows in each host application remain not tested.
Current input limits: The live capability response reports 50,000 UTF-16 code units in total per job and up to 1,000 items. Generation at those limits has not been live-tested.

Use your client's supported remote connector, native connection, or server-side request path. This guide does not promise unrestricted cross-origin browser JavaScript access to the MCP endpoint.

Browser authorization

The generic client path uses OAuth 2.1 authorization code flow with S256 PKCE and Dynamic Client Registration (DCR). It is a public-client flow: the token endpoint authentication method is none, with no shared client secret or manually copied Bearer token. The method none does not make MCP requests anonymous; each request still needs the account's valid authorization. The SDK has verified this service protocol in production; that does not verify a connection in a host application.

Discover and register the client
An unauthenticated MCP request returns 401. The client follows the protected-resource metadata indicated by WWW-Authenticate, discovers authorization metadata, and registers its own client and callback addresses.
Complete account authorization
Follow the browser sign-in and email-verification prompts. Use an authorization code once, with its matching S256 PKCE verifier.
Keep callbacks exact
Use the callback displayed or documented by that particular client. Registered redirect URIs must match exactly. Private-protocol callbacks and dynamic loopback callbacks need their own validation; an existing Web or OpenAI application callback is not a shared callback for every client.
Let the client refresh access
A supporting client uses the refresh_token grant and stores its credentials privately. One rotating refresh preserving the same account passed in the live SDK flow. Refresh and callback handling in individual hosts still need their own verification. Disconnecting a client does not itself revoke the Narrivela account or all previously issued tokens.

Do not copy an operator API key, the ChatGPT application secret, or another user's long-term credentials into a shared configuration. A client that only accepts an API key cannot be advertised as compatible with this OAuth path. Use the web studio while your client's connection is being verified.

Registration capacity

Auth0 Free includes Auth for MCP, but its entity limits are a maximum of 10 Applications and 100 ClientGrants. A new request to /oidc/register creates a new Application. Clients should save and reuse their DCR registration and client ID instead of registering again for every login.

User accounts and client Applications are different entities: 100 users do not necessarily require 100 Applications. These limits also do not establish free capacity for 100 independently registered MCP client instances. First-time registration for a new generic client is subject to the tenant's application capacity; the number of slots currently remaining has not been confirmed. Two real production DCR requests returned HTTP 201 during verification. New registrations succeeded at that time, but those responses do not measure the remaining capacity.

If capacity prevents your client from registering, use the web studio. Broader access for independently registered clients requires a confirmed capacity plan. No paid Auth0 upgrade or deletion of existing Applications has been performed.

Auth0 pricing · Auth0 entity limit policy · Auth0 DCR application creation guidance.

Client setup paths

Choose the instructions for your client. Every status is not tested; no client version, successful authorization, or marketplace approval is implied. A future passed status will identify the version, date, and exact workflow verified.

WorkBuddy: Custom connector with streamableHttp · not tested
Claude Web / Desktop: Web connector with Register automatically · not tested
Cursor: mcpServers with a remote URL · not tested
VS Code / Copilot: servers with type http · not tested
Gemini CLI: httpUrl and browser OAuth / DCR · not tested
Dify: MCP tools with DCR · not tested
n8n: MCP Client and MCP OAuth2 credential · not tested

WorkBuddy

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

Open connector management and add a custom remote connector named Narrivela. Use the configuration format requested by the interface:

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

Complete browser OAuth without a client secret. WorkBuddy's standard OAuth path requires S256, one-time codes, DCR responses that return the registered redirect_uris, and refresh support. Its preferred callback uses workbuddy://workbuddy/mcp/connector%3A<source>/oauth/callback; a client may fall back to http://127.0.0.1:{dynamic-port}/oauth/callback. Register and validate the exact address actually supplied by that client.

A production DCR protocol check using a WorkBuddy private-protocol callback returned HTTP 201 and echoed redirect_uris. That verifies registration behavior only; the WorkBuddy application has not completed authorization, tool discovery, speech generation, or download verification.

Adding a custom URL does not publish a connector in the WorkBuddy market. Official custom connector guide · Official development and OAuth specification.

Claude Web / Desktop

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

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. This DCR path is different from Use Claude’s published identity; implementation of DCR does not verify that other identity path.
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 custom connectors access the remote server from Anthropic's cloud, so it must be reachable publicly. No dedicated Narrivela player or Claude directory listing is promised. Official Claude connector guide.

Cursor

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

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 follow the OAuth prompt. A separately registered public client may use auth.CLIENT_ID and auth.scopes; this example supplies no unregistered client ID or secret. Desktop's http://localhost:8787/callback and Web / Agents' https://www.cursor.com/agents/mcp/oauth/callback are separate callback paths and must be registered and tested separately. Official Cursor MCP guide.

VS Code / Copilot

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

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"
    }
  }
}

This file uses the top-level servers field. Start and trust the server, complete browser OAuth, and enable its tools in chat. A separately registered public client may use oauth.clientId. The portable Copilot .mcp.json format uses mcpServers; do not mix those formats. Workspace or administrator policies may restrict custom servers. Official configuration reference · Official server setup guide.

Gemini CLI

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

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 a Gemini CLI session and follow the browser prompts. HTTP uses httpUrl, rather than the url field used for SSE. Automatic discovery can use DCR. The client must be able to open a browser and receive http://localhost:{dynamic-port}/oauth/callback; it also checks the authorization response's iss when supported. Headless sign-in needs a separately verified path. Official Gemini CLI MCP guide.

Dify

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

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 the tools and select them in Tool or Agent nodes. Keep the server identifier stable because workflows and exports reference it. Disabling DCR requires a separate fixed application and the exact Dify callback; that configuration is not supplied here. Dify's general HTTP support does not establish that its public-client DCR request works with Narrivela in your version. Official Dify Tools guide.

Calls use the Narrivela identity authorized by the workspace. The workflow's visitors do not automatically receive separate Narrivela accounts or free credits.

n8n

Narrivela host verification: not tested. The platform documentation describes a supported setup path; it does not prove that Narrivela authorization, tools, or downloads work in this client.

Use MCP Client for ordinary 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 an actual tool and its parameters. An older SSE-only node must not treat this HTTP address as an SSE endpoint. Use a version with HTTP and MCP OAuth2 support. MCP Server Trigger exposes n8n's own capabilities; it is not the client step for connecting to Narrivela. Official MCP Client guide · Official MCP Client Tool guide · Official MCP OAuth2 credential guide.

Workflows using the credential consume its Narrivela account's allowance. Sharing a credential does not create new-user credits. Poll the existing task instead of creating a new generation task on each loop or retry.

Core tools without a custom player

Successful tool calls return the same JSON object in a text content block and structuredContent. Read tool errors first; an error result is not a successful structured result. The speech workflow below does not require window.openai, a dedicated player, or native attachment parameters. Without a custom UI, the live SDK read get_service_capabilities and completed real generation, polling, and downloads for two short passages. Long-text and large-batch admission, splitting, and pagination use the same server implementation and isolated SDK fixtures; this is not evidence of live production generation of large passages or large batches. Check the actual discovered tools and current capability response.

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 below with the actual returned job ID. Start at offset 0; a page limit of 100 is an example, with a maximum of 1000:

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

Service input and concurrency limits still apply, and a client's context limit can be smaller. Public style prompts are unavailable. WAV and MP3 are speech output choices; this guide does not promise unlimited text or universal file uploads.

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 ordinary HTTPS links. Whether a host shows an embedded player depends on that host.

Use the whole returned URL, including its signature query, and keep it private. Anyone holding a valid link can retrieve that result while the link is valid. Do not put it in a public page or public log. A link's exp is its access expiry; expires_at describes file retention. The same signed-in account can query its retained job again to obtain fresh links. An expired or leaked status link cannot renew itself. Files already downloaded stay usable after server retention ends.

Local text files and optional interfaces

For UTF-8 text, read the authorized file in your client and send complete text. For JSONL, parse its records locally and send ordered, unique {id,text} items. For documents, extract readable text first. A remote server cannot read a path on your client's computer. If the input exceeds the tool limit, use the web studio and check its limits.

show_speech_job is an optional progress and download card. The basic workflow uses get_speech_job and its links whether or not the host renders that card. submit_speech_file, visuals for export_speech_html, and optional native video inputs need real attachment references supported by their host. OpenAI openai/fileParams does not make other clients' attachment URLs compatible. Do not invent file IDs, send local filesystem paths, or substitute arbitrary cloud URLs. This guide does not advertise a generic server-side HTML/video upload path.

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.

Registry and marketplace status

MCP Registry: registered

The com.narrivela/narrivela record was published on October 14, 2026 (China Standard Time), at version 0.6.0. The official record is active and marked as the latest version, with the remote Streamable HTTP endpoint https://app.narrivela.com/mcp. View the official Registry record.

Registration provides discovery metadata; it does not prove acceptance by WorkBuddy, Claude, Cursor, OpenAI, or another marketplace. A registry entry does not guarantee search indexing, ranking, or AI recommendations. Connections from the seven hosts listed here remain not tested. ChatGPT public installation and Codex public installation have their own status.

When a connection fails

Record the client version, time, and non-sensitive error code. Check the HTTP transport, browser authorization, email verification, and the actual callback shown by the client. Authorization success alone does not verify speech generation or downloads. Contact support without sharing passwords, tokens, signed download URLs, or full private scripts.