# Wisprs for ChatGPT, Codex, Claude & Claude Code

Wisprs exposes a secure remote Model Context Protocol endpoint at `https://wisprs.co/api/mcp`. Contract v1.8 adds plan-aware text-to-speech voice discovery to the transcript, library, folder, usage, editing, retry, sharing, and private-media handoff surface.

The hosted connector is currently a **private reviewer release**. Public installation links remain unavailable until platform review and Wisprs' release gates are complete.

## Public v1 tools

| Tool | Result | Required scope |
|---|---|---|
| `transcribe_url` | Returns a durable `op_…` receipt immediately | `transcripts:write` |
| `get_video_transcript` | Returns the existing caption track of a public YouTube, TikTok, or Instagram video as text (no speech-to-text, no minutes used), or `no_captions` | `transcripts:read` |
| `get_private_media_upload_handoff` | Returns the authenticated Wisprs uploader without exposing file bytes or upload tokens to the model | `transcripts:write` |
| `list_tts_voices` | Returns a bounded plan-filtered voice catalog with opaque handles | `tts:read` |
| `synthesize_speech` | Starts a metered text-to-speech job and returns a durable receipt | `tts:write` |
| `list_tts_syntheses` | Returns bounded text-to-speech history with short untrusted previews | `tts:read` |
| `get_tts_audio` | Returns a short-lived private download URL for a completed synthesis | `tts:read` |
| `list_meeting_sessions` | Returns bounded meeting capture status with consent state | `meetings:read` |
| `schedule_meeting_capture` | Schedules a meeting agent after explicit recording consent | `meetings:write` |
| `cancel_meeting_capture` | Cancels a not-yet-dispatched meeting agent after confirmation | `meetings:write` |
| `list_support_tickets` | Returns the connected user's own support tickets with bounded previews | `support:read` |
| `create_support_ticket` | Creates a bounded support request for the authenticated user | `support:write` |
| `list_webhook_endpoints` | Returns webhook endpoints with signing secrets redacted | `webhooks:read` |
| `create_webhook_endpoint` | Creates an HTTPS webhook endpoint after SSRF-safe DNS validation | `webhooks:write` |
| `update_webhook_endpoint` | Updates a tenant-owned webhook URL or active state | `webhooks:write` |
| `delete_webhook_endpoint` | After confirmation, reversibly disables a webhook endpoint | `webhooks:write` |
| `list_organization_members` | Returns workspace members without private account fields | `organization:read` |
| `list_creator_packs` | Returns the bounded creator packs available to the account | `creator:read` |
| `list_creator_templates` | Returns bounded creator workflow templates and their outcomes | `templates:read` |
| `list_notifications` | Returns bounded in-app notifications for the authenticated user | `notifications:read` |
| `mark_notifications_read` | Marks selected or all unread notifications as read | `notifications:write` |
| `list_operations` | Returns bounded operation history without payloads or source URLs | `operations:read` |
| `get_job_status` | Returns queued, running, completed, failed, or canceled state | `operations:read` |
| `get_transcript` | Returns bounded transcript pages from a `tr_…` handle | `transcripts:read` |
| `get_transcript_artifact` | Returns bounded pages of generated or translated content | `ai:transform` |
| `search_library` | Returns bounded ranked snippets from the connected tenant | `library:search` |
| `list_transcripts` | Returns one signed-keyset-paginated library page | `transcripts:read` |
| `get_transcription_metadata` | Returns bounded metadata without transcript text | `transcripts:read` |
| `list_folders` | Returns tenant-owned folders and live media counts | `library:read` |
| `get_usage_and_limits` | Returns plan usage, limits, and reset windows without billing secrets | `usage:read` |
| `create_folder` | Creates a tenant-owned media folder through a durable operation | `library:write` |
| `rename_folder` | Renames a tenant-owned folder without changing its contents | `library:write` |
| `move_transcript_to_folder` | Files or unfiles one tenant-owned transcript | `library:write` |
| `delete_folder` | After explicit confirmation, soft-deletes a folder and preserves its media | `library:write` |
| `rename_transcript` | Renames a transcript only when its expected revision is current | `transcripts:write` |
| `edit_transcript_text` | Applies a confirmed bounded literal edit with a revision guard | `transcripts:write` |
| `retry_transcription` | Requeues a failed transcript from retained source media after confirmation | `transcripts:write` |
| `create_share_link` | Creates an explicitly confirmed, expiring public transcript link | `sharing:write` |
| `revoke_share_link` | Revokes a public transcript link through an idempotent operation | `sharing:write` |
| `export_transcript` | Returns a private one-hour MCP resource for six export formats | `transcripts:export` |
| `summarize_transcript` | Starts durable summary generation | `ai:transform` |
| `generate_chapters` | Starts durable chapter generation | `ai:transform` |
| `repurpose_transcript` | Starts show-notes, thread, blog, or quote generation | `ai:transform` |
| `translate_transcript` | Starts a language-specific translation | `ai:transform` |

## ChatGPT and Codex

The OpenAI distribution is a universal plugin containing a registered remote MCP connection and provider-neutral operating instructions. During private review, use the reviewer package and account supplied by Wisprs. After approval, this section will link to the public directory listing.

The host performs OAuth discovery against Wisprs, requests only the scopes needed for the selected outcome, and calls the same tools above. Do not enter a Wisprs API key into a ChatGPT conversation.

## Claude and Claude Code

The Anthropic distribution contains a Claude plugin manifest plus this remote MCP definition:

```json
{
  "mcpServers": {
    "wisprs": {
      "type": "http",
      "url": "https://wisprs.co/api/mcp"
    }
  }
}
```

During private review, install only the signed package or marketplace source supplied by Wisprs. After Anthropic approval, this section will link to the public connector and plugin listings.

## The durable workflow

1. Ask the host to transcribe a public HTTPS media URL.
2. Keep the returned `op_…` receipt. It is safe to retry the original call with the same idempotency key.
3. Call `get_job_status` later. Do not resubmit media merely because processing is still running.
4. When the operation succeeds, use its opaque `tr_…` handle with `get_transcript`.
5. Follow the returned cursor until `nextCursor` is null.
6. For generated content, call `get_transcript_artifact` with the completed result metadata. For exports, read the exact returned `wisprs://exports/res_…` resource before it expires.

Example prompts:

```text
Transcribe this public recording and tell me when it is ready: https://example.com/recording.mp3
Check operation op_… with get_job_status and report its current state.
Retrieve transcript tr_… page by page and preserve source order.
Find where we discussed pricing in my Wisprs library.
Summarize transcript tr_…, then retrieve the generated artifact.
Export transcript tr_… as DOCX without placing the file contents in chat.
```

## Security and tenancy

- Remote host connections use OAuth; `transcripts:write` and `transcripts:read` are separate grants.
- Transcript and operation identifiers are opaque. A valid handle never bypasses tenant authorization.
- Media intake accepts public HTTPS destinations only. Private networks, unsafe redirects, unsupported media, and oversized responses are rejected.
- Revoked or expired grants fail closed.
- Channel telemetry excludes prompts, transcript text, media URLs, filenames, access tokens, email addresses, and raw IP addresses.

## Developer stdio connection

The existing `@wisprs/mcp` npm package is the developer-controlled alternative for stdio hosts. It uses a Wisprs API key and is separate from the hosted OAuth directory listings.

```bash
WISPRS_API_KEY=wisprs_sk_your_api_key npx @wisprs/mcp
```

Example stdio configuration:

```json
{
  "mcpServers": {
    "wisprs": {
      "command": "npx",
      "args": ["@wisprs/mcp"],
      "env": { "WISPRS_API_KEY": "wisprs_sk_your_api_key" }
    }
  }
}
```

Keep the key in the host's secret or environment configuration, never in a prompt or committed config file. Scope the key to the operations the local package needs.

## Troubleshooting

### No tools appear

Reconnect, confirm that OAuth completed, and start a new conversation so the host refreshes its tool list. Reviewer access also requires the host client or account to be in the active rollout cohort.

### The media URL is rejected

Use a public HTTPS URL that resolves directly to supported media. URLs resolving to private or local addresses, redirects to unsafe destinations, and responses above the intake limit are blocked.

### The operation is still running

Long media is asynchronous by design. Preserve the `op_…` receipt and check it later; do not create a duplicate operation.

### Access was revoked

Reconnect through the host. A revoked grant cannot read prior operation or transcript handles without fresh, valid authorization.