Giggy MCP Server

Giggy MCP — text-to-speech and recorded transcription for AI agents

Giggy MCP is a remote Streamable HTTP Model Context Protocol (MCP) server for using Giggy text-to-speech and recorded-audio speech-to-text from coding agents and AI clients.

It provides Giggy speech tools to Codex, Claude Code, Cursor, VS Code, Cline, Windsurf-compatible clients, and other MCP clients.

MCP registry and plugin directories

Giggy's remote speech MCP endpoint is:

https://giggy.ai/mcp

This repository contains the publication artifacts for:

• Official MCP Registry: server.json
• OpenAI / Codex: openai-plugin/
• Claude Code: .claude-plugin/plugin.json

See directory submission status and requirements.

A public registry listing, plugin submission, and approved plugin publication are separate steps. Consult the submission document for verified status.

Install for AI coding agents

Agent Skill — Codex and Claude Code

npx skills add giggy-ai/giggy-mcp --skill giggy-speech

The skill guides TTS, recorded STT, live microphone WebSocket STT, SDK and Pipecat integrations without requiring an MCP connection. Executing MCP tools still requires an authenticated connection. Check the current package and workflow guide at https://giggy.ai/llms-full.txt before implementing.

Claude Code plugin

claude plugin marketplace add giggy-ai/giggy-mcp
claude plugin install giggy-speech@giggy

Codex

Follow the existing Codex MCP setup below.

Example prompt

"Use Giggy to list available English voices, generate a short Batch speech sample saying 'Hello from Giggy', and return the completed audio URL."

Discover Giggy

• Official MCP Registry
• Speech API docs
• Runnable examples
• Directory submission status

Choose guidance, tool execution or publication

For Codex, use the environment-backed TOML below. Claude Code has its JSON example below. Cursor, VS Code, Cline and Windsurf client examples are in examples/. Use the configuration format supported by your installed client; do not paste a shared key into manifests or chat.

The API-key bearer setup is the documented path in this repository. OAuth is separate: verify the hosted server, client and per-user authorization together before claiming it works. Candidate OAuth source code is not a verified hosted flow. Respect the user's budget and existing authorization; validating setup does not authorize paid Fast/Streaming or microphone calls.

For a code-only first task ask: "Use the Giggy skill to implement explicit Batch TTS that saves SDK audio bytes, or recorded STT that retrieves final text. MCP workflows poll the returned UUID for their completed result URL. Check current docs; do not execute requests." For a live integration ask: "Implement the documented live WebSocket flow, preserving readiness, stop and final verification; write code only."

Quick setup

Use Giggy MCP with Codex

Set GIGGY_API_KEY in your environment, then add to ~/.codex/config.toml:

[mcp_servers.giggy-speech]
url = "https://giggy.ai/mcp"
bearer_token_env_var = "GIGGY_API_KEY"

Use Giggy MCP with Claude Code

Set GIGGY_API_KEY, then configure:

{
  "mcpServers": {
    "giggy-speech": {
      "type": "http",
      "url": "https://giggy.ai/mcp",
      "headers": { "Authorization": "Bearer ${GIGGY_API_KEY}" }
    }
  }
}

Keep API keys out of configuration files committed to source control.

Remote MCP server

https://giggy.ai/mcp

Transport:

Streamable HTTP

The current Giggy MCP endpoint is stateless and accepts POST requests.

Authentication

Use a Giggy API key:

Authorization: Bearer $GIGGY_API_KEY

Giggy API keys begin with:

giggy_sk_

Keep the key in your MCP client's secret or environment configuration.

Do not:

• put it in ordinary prompts
• commit it to source control
• embed it in browser JavaScript

Speech tools

This repository documents these Giggy speech tools:

list_voices
list_my_voices
generate_speech
get_speech_generation
transcribe_audio

Read the connected server's tool schemas before calling these tools. Recorded transcription is asynchronous admission, followed by durable status/result retrieval. MCP does not transport live microphone frames; use the Python or Node.js SDK for that workflow.

Transcribe recorded audio with a coding assistant

Connect MCP with your own Giggy API key, then ask: "Use Giggy to transcribe my authorised recording with the available recorded-audio tool, retain the generation UUID, and retrieve the completed transcript."

The assistant must inspect transcribe_audio's current schema, prepare the supported input and use one idempotency key per intended operation. Poll get_speech_generation without resubmitting. Retrieve the canonical transcript only after completion; do not treat admission as final text. Check pricing and limits before paid usage. The current transcript contract does not provide speaker diarization, word timestamps, sentiment or PII redaction.

For SDKs, Pipecat, n8n and learning resources, use the developer tool guide.

Recommended speech workflow

1. Call list_voices or list_my_voices.
2. Select the exact returned voice_id.
3. Call generate_speech with explicit mode=batch for the free queued workflow; paid modes require authorization.
4. Supply a fresh idempotency_key for each new intended generation.
5. Save generation.generation_uuid.
6. Call get_speech_generation while the status is queued or processing.
7. When the status becomes completed, use generation.result.url.

Do not resubmit a new generation while polling an existing generation.

Use Giggy MCP with Codex

Set:

export GIGGY_API_KEY="giggy_sk_..."

Then add this to:

~/.codex/config.toml

[mcp_servers.giggy-speech]
url = "https://giggy.ai/mcp"
bearer_token_env_var = "GIGGY_API_KEY"

A ready-to-copy version is included at:

examples/codex-config.toml

Verify:

codex mcp list

Use Giggy MCP with Claude Code

Set:

export GIGGY_API_KEY="giggy_sk_..."

A project MCP configuration is included at:

examples/claude-code.mcp.json

Its contents are:

{
  "mcpServers": {
    "giggy-speech": {
      "type": "http",
      "url": "https://giggy.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${GIGGY_API_KEY}"
      }
    }
  }
}

Copy that configuration to:

.mcp.json

in the project where Claude Code should use Giggy.

Then run:

claude mcp list

or use:

/mcp

inside Claude Code.

Other MCP clients

Ready-to-copy client configurations are included for:

Cursor

Set:

export GIGGY_API_KEY="giggy_sk_..."

Copy or merge:

examples/cursor.mcp.json

into:

.cursor/mcp.json

for project configuration, or:

~/.cursor/mcp.json

for global configuration.

VS Code

Copy or merge:

examples/vscode.mcp.json

into:

.vscode/mcp.json

This example uses the VS Code Local harness and its password-style ${input:giggy-api-key} prompt. It is not a universal Copilot-harness configuration: input/command secrets from the VS Code format are not forwarded to that harness. Check the official MCP configuration reference for the environment-variable header format supported by your selected harness. Do not replace a secret placeholder with a key in a committed file.

Cline

Open Cline's MCP server configuration and copy the contents of:

examples/cline.mcp.json

Replace:

YOUR_GIGGY_API_KEY

in your local configuration only.

Do not commit the configured file.

Windsurf-compatible clients

For installations that use:

~/.codeium/windsurf/mcp_config.json

merge the contents of:

examples/windsurf.mcp.json

and replace:

YOUR_GIGGY_API_KEY

in the local configuration only.

Raw MCP examples

Set:

export GIGGY_API_KEY="giggy_sk_..."

Initialize:

./examples/initialize.sh

List tools:

./examples/list-tools.sh

List public voices:

./examples/list-voices.sh

Important behavior

generate_speech returns durable generation metadata.

It does not return live MP3 or PCM audio bytes through MCP.

For progressive PCM audio, use:

POST https://api.giggy.ai/v1/text-to-speech

with:

mode=streaming
output_format=pcm_24000

Developer resources

Speech API documentation:

https://giggy.ai/docs/speech-api

OpenAPI:

https://api.giggy.ai/v1/openapi.json

Runnable examples:

https://github.com/giggy-ai/giggy-examples

Pricing:

https://giggy.ai/pricing

Official SDK and runnable examples:

• Giggy JavaScript/TypeScript SDK
• Giggy integration examples