Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Cartesia MCP server

Vendor MCP
Open markdown

The Cartesia MCP connector routes your AI agent's tool calls to Cartesia's own MCP server through Scalekit. Each user connects their own Cartesia access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 19 tools.

Tools
19
What they doRead · write · destructive
9 · 7 · 39 read7 write3 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Cartesia MCP connection

    In AgentKit > Connections, create a Cartesia MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Register your Cartesia API key with Scalekit so it can authenticate requests to the Cartesia MCP server on behalf of your users. Cartesia MCP uses API key authentication: the key is sent as a Bearer token.

    1. Create a Cartesia API key

    2. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Cartesia MCP and click Create.
      • Note the Connection name — use this as connection_name in your code (for example, cartesiamcp).
    3. Add a connected account

      Connected accounts link a specific user identifier in your system to a Cartesia API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • Open the connection and click the Connected Accounts tab → Add account.
      • Fill in Your User’s ID and API Key, then click Save.

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { ConnectorStatus } from '@scalekit-sdk/node'
      const authorizationDetails = {
      details: {
      case: 'staticAuth',
      value: { details: { token: process.env.USER_API_KEY } },
      },
      };
      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
      connectionName: 'cartesiamcp',
      identifier: 'user_123',
      authorizationDetails,
      });
      // Make sure the account is ACTIVE before the first tool call.
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
      ({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
      connectionName: 'cartesiamcp',
      identifier: 'user_123',
      authorizationDetails,
      }));
      }
  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'cartesiamcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Cartesia MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'cartesiamcp_list_accents',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Cartesia MCP server credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • cartesiamcp_download_fileFetch a Cartesia cloud-stored file by ID.Read-only

    Download file

    Fetch a Cartesia cloud-stored file by ID. Returns a 24-hour `download_url` for hosted and remote clients. Also writes a copy to `OUTPUT_DIRECTORY` on the MCP server host (for local `uvx` or server-side `speech_to_text` in the same session). On hosted MCP those local copies are under a temp directory and purged after a TTL. Use the `file_id` from a prior `text_to_speech` call (`save=true`, the default) or from playground TTS history. Parameters ---------- file_id : str Cloud file ID (e.g. from `text_to_speech`). format : typing.Optional[DownloadFormat] Pass `playback` to wrap raw PCM as WAV in the download link and local file.

    Inputs

    file_idstringrequired
    Cloud file ID (e.g. from `text_to_speech`).
    formatstring
    Pass `playback` to wrap raw PCM as WAV in the download link and local file.one of playback
  • cartesiamcp_get_pronunciation_dictParameters ---------- dict_id : str Pronunciation dictionary ID.Read-only

    Get pronunciation dictionary

    Parameters ---------- dict_id : str Pronunciation dictionary ID.

    Inputs

    dict_idstringrequired
    Pronunciation dictionary ID.
  • cartesiamcp_get_voiceParameters ---------- voice_id : str The ID of the voice to get.Read-only

    Get voice

    Parameters ---------- voice_id : str The ID of the voice to get. request_options : typing.Optional[RequestOptions] Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).

    Inputs

    voice_idstringrequired
    The ID of the voice to get.
    request_optionsobject
    Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).
  • cartesiamcp_list_accentsList the official accent catalog from GET /accents.Read-only

    List accents

    List the official accent catalog from GET /accents. Each entry includes the canonical accent `id` plus display metadata (`name`, `language`, `locale`, `is_locale_default`, `is_localizable`). Pass `id` to `clone_voice`, `add_voice_accents`, `delete_voice_accent`, and `localize_voice`. Display names are rejected on this API version. Parameters ---------- request_options : typing.Optional[RequestOptions] Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).

    Inputs

    request_optionsobject
    Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).
  • cartesiamcp_list_agent_modelsList LLMs available for Managed Agents from GET /v1/agents/models.Read-only

    List agent models

    List LLMs available for Managed Agents from GET /v1/agents/models. Use these `id` values for an agent's `model.id` (and explicit fallback model ids). Do not invent model ids. Each row includes provider, display name, latency, and token pricing. Returns the full catalog (pagination is followed server-side). Parameters ---------- request_options : typing.Optional[RequestOptions] Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).

    Inputs

    request_optionsobject
    Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).
  • cartesiamcp_list_modelsList callable Sonic (TTS) and Ink (STT) model ids from GET /models.Read-only

    List models

    List callable Sonic (TTS) and Ink (STT) model ids from GET /models. Each row has `id` and `capability` (`tts` or `stt`). TTS rows include `supported_languages`, the sorted synthesis language codes that model accepts. STT rows include `modes` (`stream` and/or `batch`). Pass `id` to `text_to_speech` as `model_id` or to `speech_to_text` as `model`. Omit model on those tools when you want the API default. Preview ids (`sonic-preview`, `ink-preview`) are included when callable. Parameters ---------- capability : typing.Optional[Literal["tts", "stt"]] Filter to TTS or STT. Omit to return both. request_options : typing.Optional[RequestOptions] Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).

    Inputs

    capabilitystring
    Filter to TTS or STT. Omit to return both.one of ttsstt
    request_optionsobject
    Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).
  • cartesiamcp_list_pronunciation_dictsList pronunciation dictionaries for the authenticated user.Read-only

    List pronunciation dictionaries

    List pronunciation dictionaries for the authenticated user. Parameters ---------- limit : typing.Optional[int] Number of dictionaries per page (1–100). starting_after : typing.Optional[str] Cursor: dictionary ID to start after. ending_before : typing.Optional[str] Cursor: dictionary ID to end before.

    Inputs

    ending_beforestring
    Cursor: dictionary ID to end before.
    limitinteger
    Number of dictionaries per page (1–100).default 10
    starting_afterstring
    Cursor: dictionary ID to start after.
  • cartesiamcp_list_voicesParameters ---------- limit : typing.Optional[int] The number of Voices to return per page, ranging between 1 and 100.Read-only

    List voices

    Parameters ---------- limit : typing.Optional[int] The number of Voices to return per page, ranging between 1 and 100. starting_after : typing.Optional[str] A cursor to use in pagination. `starting_after` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, ending with `voice_abc123`, your subsequent call can include `starting_after=voice_abc123` to fetch the next page of the list. ending_before : typing.Optional[str] A cursor to use in pagination. `ending_before` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, starting with `voice_abc123`, your subsequent call can include `ending_before=voice_abc123` to fetch the previous page of the list. is_owner : typing.Optional[bool] Whether to only return voices owned by the current user. is_starred : typing.Optional[bool] Whether to only return starred voices. gender : typing.Optional[GenderPresentation] The gender presentation of the voices to return. language : typing.Optional[str] Filter voices by language or locale, such as `en`, `it`, or `en_GB`. A locale returns accents for that region; a language alone returns all accents for that language. Both `-` and `_` separators are accepted. q : typing.Optional[str] Search voices by name, description, or voice ID. expand : typing.Optional[typing.Sequence[str]] Additional fields to include in the response, such as `preview_file_url`. request_options : typing.Optional[RequestOptions] Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).

    Inputs

    ending_beforestring
    A cursor to use in pagination. `ending_before` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, starting with `voice_abc123`, your subsequent call can include `ending_before=voice_abc123` to fetch the previous page of the list.
    expandarray
    Additional fields to include in the response, such as `preview_file_url`.
    genderstring
    The gender presentation of the voices to return.one of masculinefemininegender_neutral
    is_ownerboolean
    Whether to only return voices owned by the current user.
    is_starredboolean
    Whether to only return starred voices.
    languagestring
    Filter voices by language or locale, such as `en`, `it`, or `en_GB`. A locale returns accents for that region; a language alone returns all accents for that language. Both `-` and `_` separators are accepted.
    limitinteger
    The number of Voices to return per page, ranging between 1 and 100.default 10
    qstring
    Search voices by name, description, or voice ID.
    request_optionsobject
    Request-specific configuration (timeout, headers, query params, extra body fields, max_retries).
    starting_afterstring
    A cursor to use in pagination. `starting_after` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, ending with `voice_abc123`, your subsequent call can include `starting_after=voice_abc123` to fetch the next page of the list.