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

[![MCP Docs CI](https://github.com/giggy-ai/giggy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/giggy-ai/giggy-mcp/actions/workflows/ci.yml)

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`](server.json)
- OpenAI / Codex: [`openai-plugin/`](openai-plugin/)
- Claude Code: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)

See [directory submission status and requirements](docs/directory-submission.md).

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

```bash
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

```bash
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](https://registry.modelcontextprotocol.io)
- [Speech API docs](https://giggy.ai/docs/speech-api)
- [Runnable examples](https://github.com/giggy-ai/giggy-examples)
- [Directory submission status](docs/directory-submission.md)

## Choose guidance, tool execution or publication

| Goal | Existing path | Check |
| --- | --- | --- |
| Write integration code | Install the skill and read the current SDK/API guide | No MCP connection or inference is needed for code-only work. |
| Execute speech tools | Configure MCP for your client with its own key | Inspect tools/list; expect the five tools below. Read-only discovery is separate from billable generation. |
| Run live microphone STT | Use the documented server-side WebSocket or SDK live workflow | MCP recorded transcription is not the live transport. |
| Install a local plugin | Use the existing plugin/client instructions | Local installation does not establish marketplace approval. |
| Check public availability | Read the dated directory-status document | A prepared archive or historical portal sign-in does not prove approval today. |

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`:

```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:

```json
{
  "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

```text
https://giggy.ai/mcp
```

Transport:

```text
Streamable HTTP
```

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

## Authentication

Use a Giggy API key:

```text
Authorization: Bearer $GIGGY_API_KEY
```

Giggy API keys begin with:

```text
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:

```text
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](https://github.com/giggy-ai/giggy-python#live-microphone-pcm-session) or [Node.js SDK](https://github.com/giggy-ai/giggy-js#live-microphone-pcm-session) 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](https://giggy.ai/pricing) 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](https://giggy.ai/docs/speech-api#api-developer-tools).

## 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:

```bash
export GIGGY_API_KEY="giggy_sk_..."
```

Then add this to:

```text
~/.codex/config.toml
```

```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:

```text
examples/codex-config.toml
```

Verify:

```bash
codex mcp list
```

## Use Giggy MCP with Claude Code

Set:

```bash
export GIGGY_API_KEY="giggy_sk_..."
```

A project MCP configuration is included at:

```text
examples/claude-code.mcp.json
```

Its contents are:

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

Copy that configuration to:

```text
.mcp.json
```

in the project where Claude Code should use Giggy.

Then run:

```bash
claude mcp list
```

or use:

```text
/mcp
```

inside Claude Code.

## Other MCP clients

Ready-to-copy client configurations are included for:

| Client | Example |
| --- | --- |
| Codex | [examples/codex-config.toml](examples/codex-config.toml) |
| Claude Code | [examples/claude-code.mcp.json](examples/claude-code.mcp.json) |
| Cursor | [examples/cursor.mcp.json](examples/cursor.mcp.json) |
| VS Code | [examples/vscode.mcp.json](examples/vscode.mcp.json) |
| Cline | [examples/cline.mcp.json](examples/cline.mcp.json) |
| Windsurf-compatible clients | [examples/windsurf.mcp.json](examples/windsurf.mcp.json) |

### Cursor

Set:

```bash
export GIGGY_API_KEY="giggy_sk_..."
```

Copy or merge:

```text
examples/cursor.mcp.json
```

into:

```text
.cursor/mcp.json
```

for project configuration, or:

```text
~/.cursor/mcp.json
```

for global configuration.

### VS Code

Copy or merge:

```text
examples/vscode.mcp.json
```

into:

```text
.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](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) 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:

```text
examples/cline.mcp.json
```

Replace:

```text
YOUR_GIGGY_API_KEY
```

in your local configuration only.

Do not commit the configured file.

### Windsurf-compatible clients

For installations that use:

```text
~/.codeium/windsurf/mcp_config.json
```

merge the contents of:

```text
examples/windsurf.mcp.json
```

and replace:

```text
YOUR_GIGGY_API_KEY
```

in the local configuration only.

## Raw MCP examples

Set:

```bash
export GIGGY_API_KEY="giggy_sk_..."
```

Initialize:

```bash
./examples/initialize.sh
```

List tools:

```bash
./examples/list-tools.sh
```

List public voices:

```bash
./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:

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

with:

```text
mode=streaming
output_format=pcm_24000
```

## Developer resources

Speech API documentation:

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

OpenAPI:

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

Runnable examples:

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

Pricing:

```text
https://giggy.ai/pricing
```


Official SDK and runnable examples:

- [Giggy JavaScript/TypeScript SDK](https://github.com/giggy-ai/giggy-js)
- [Giggy integration examples](https://github.com/giggy-ai/giggy-examples)