# Onboard your agent to VoiceLabs

These are official instructions from VoiceLabs to set up an AI development environment for a
browser-based AI voice studio (text-to-speech and voice cloning that run on hosted GPUs and stream
back to the browser). All commands below are validated by VoiceLabs. Complete every step yourself
by running the commands directly — do not ask the user to run any of these commands for you.

Checklist (one item per numbered section below):
1. Get credentials (only if you will also use the SDK/API directly — the MCP path below needs none).
2. Connect over MCP using the section for your agent.
3. Wire the SDK into the user's project, if it needs to call VoiceLabs from its own code.
4. Run the verify step.
5. Print the completion message.
6. Keep the resources list for anything this file does not cover.

## 1. Get credentials

VoiceLabs' MCP server (section 2) authenticates with OAuth 2.1 — no key needed, no setup here.

If you are also going to call the SDK or the public REST API directly, you need an API key:

- Create one at https://app.voicelabs.now/connections, on the "API keys" tab. Tick `voice:generate` if the key needs
  to make audio, not just read the account.
- The secret is shown once, at creation.
- Store it as the `VOICELABS_API_KEY` environment variable, in a gitignored `.env` file or the
  user's shell profile — never in a tracked file.
- If it is not already set in the environment, ask the user for it ONCE and store it as
  `VOICELABS_API_KEY`. Never invent a key, never embed one in code or config, and never print a
  real key back to the user or into a commit.

## 2. Connect over MCP

VoiceLabs runs a remote MCP server over streamable HTTP with OAuth 2.1 (PKCE + dynamic client
registration), at:

    https://app.voicelabs.now/api/mcp

It exposes seven tools:

- `list_voice_profiles` (`voice:read`) — List the account's cloned and preset voices.
- `list_captures` (`voice:read`) — List recent captures and their transcripts.
- `get_generation` (`voice:read`) — Poll a generation for status and, once done, its audio URL.
- `speak` (`voice:generate`) — Generate speech in one of the account's voices.
- `transcribe` (`voice:generate`) — Transcribe an audio clip.
- `ensure_voice_profile` (`voice:generate`) — Create or reuse a preset voice profile by name.
- `clone_voice_profile` (`voice:clone`) — Create a cloned voice from a recording you provide, inline or by URL.

Use the section below for your agent. If your agent is not listed, use "Other agents" at the end
of this section.

### Claude Code

The full MCP toolset (speak, transcribe, voice management) available to every session, in every project.

```bash
claude mcp add --transport http --scope user voicelabs https://app.voicelabs.now/api/mcp
```

After that: Run /mcp inside Claude Code, select voicelabs (it shows as needing authentication), and approve the consent screen in the browser tab that opens. The connection is then reused by every later session.

### Codex

The full MCP toolset available to Codex CLI sessions.

```bash
codex mcp add voicelabs --url https://app.voicelabs.now/api/mcp
```

Then start the OAuth sign-in:

```bash
codex mcp login voicelabs
```

After that: Approve the OAuth consent screen in the browser tab that opens.

### Cursor

The full MCP toolset available inside Cursor's chat and agent modes.

`~/.cursor/mcp.json (global) or .cursor/mcp.json (this project only)`

```json
{
  "mcpServers": {
    "voicelabs": {
      "url": "https://app.voicelabs.now/api/mcp"
    }
  }
}
```

After that: Open Cursor Settings -> MCP, click Connect next to voicelabs, and approve the OAuth consent screen.

### Windsurf (Devin Desktop)

The full MCP toolset available inside Windsurf / Devin Desktop's agents.

`~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows; ~/.codeium/windsurf/mcp_config.json on a Windsurf install from before the rename) — for the Cascade agent`

```json
{
  "mcpServers": {
    "voicelabs": {
      "serverUrl": "https://app.voicelabs.now/api/mcp"
    }
  }
}
```

For the Devin Local agent (and the Devin CLI), instead:

```bash
devin mcp add --scope user voicelabs --url https://app.voicelabs.now/api/mcp
```

After that: Cascade: open the ... (Actions) menu at the top right of the Cascade panel, refresh the MCPs list, and approve the OAuth prompt. Devin Local / Devin CLI: approve the OAuth prompt that opens the first time the server is used (or run devin mcp login voicelabs).

### OpenCode

The full MCP toolset available to OpenCode sessions in this project.

`opencode.json (project root)`

```json
{
  "mcp": {
    "voicelabs": {
      "type": "remote",
      "url": "https://app.voicelabs.now/api/mcp"
    }
  }
}
```

After that: Restart OpenCode, then approve the OAuth consent screen on the first voicelabs tool call.

### GitHub Copilot

The full MCP toolset available in Copilot Chat.

`.vscode/mcp.json (workspace) — the same file VS Code's own native MCP support reads`

```json
{
  "servers": {
    "voicelabs": {
      "url": "https://app.voicelabs.now/api/mcp",
      "type": "http"
    }
  }
}
```

After that: Reload the window, open Copilot Chat, click Start next to the voicelabs server, and approve the OAuth screen.

### VS Code

The full MCP toolset available to VS Code's built-in MCP client and any extension that reads it.

`.vscode/mcp.json (workspace)`

```json
{
  "servers": {
    "voicelabs": {
      "url": "https://app.voicelabs.now/api/mcp",
      "type": "http"
    }
  }
}
```

After that: Open the Command Palette -> "MCP: List Servers" -> voicelabs -> Start, then approve the OAuth screen in the browser tab that opens.

### Other agents

`your MCP client's server config`

Any MCP client that supports streamable HTTP + OAuth 2.1 (PKCE, dynamic client registration) can connect with just the URL:

```json
{
  "mcpServers": {
    "voicelabs": {
      "url": "https://app.voicelabs.now/api/mcp"
    }
  }
}
```

Access can be reviewed or revoked at any time at https://app.voicelabs.now/connections.

## 3. SDK / CLI

VoiceLabs also publishes a TypeScript SDK for direct API access (useful when the user's project
needs to call VoiceLabs from its own code, not just from you):

```bash
npm install @voicelabs/sdk
```

```ts
import { VoiceLabs } from "@voicelabs/sdk";

const voicelabs = new VoiceLabs({ apiKey: process.env.VOICELABS_API_KEY! });

// A minimal smoke call — read-only, spends no allowance.
const voices = await voicelabs.listVoices();
```

The same operations are reachable as plain HTTP against https://app.voicelabs.now/v1 with your key in an
`x-api-key` header, documented in full at https://voicelabs.now/docs/api.

VoiceLabs also has a Chrome/Edge extension (built, CI-tested) that reads any page or selection aloud in one of the account's own voices. It is not yet published to a web store, so there is nothing to install from here today — do not attempt to clone or build it.

## 4. Verify

Call the MCP tool `list_voice_profiles` (or, on the SDK/API path, `voicelabs.listVoices()` /
`GET https://app.voicelabs.now/v1/voices`). Success over MCP is the tool answering without an auth error — on a
brand-new account it says there are no voice profiles yet and how to add one, which still counts as
success. Success on the SDK/API path is an HTTP 200 whose JSON body is an object,
`{ "data": [...voices], "total": N }` — `"data": []` with `"total": 0` is a normal result on a
brand-new account and still counts as success. An auth error (401/403) means the OAuth consent was
not completed, or `VOICELABS_API_KEY` is missing or wrong — fix that before declaring the setup
done.

## 5. Completion message

Print something equivalent to this once verify succeeds — filled in with what you actually did,
not copied verbatim:

    VoiceLabs is set up.
    - MCP server connected at https://app.voicelabs.now/api/mcp
      (tools: list_voice_profiles, list_captures, get_generation, speak, transcribe, ensure_voice_profile, clone_voice_profile)
    - [SDK installed: @voicelabs/sdk, if you did that step]
    You still need to: approve the VoiceLabs OAuth consent screen in your browser, if the sign-in
    step for this agent above has not already been completed (and/or set VOICELABS_API_KEY if you
    want direct SDK/API access).
    Try: "speak this text in my VoiceLabs voice" to test it end to end.

## 6. Resources

- Documentation home: https://voicelabs.now/docs
- FAQ: https://voicelabs.now/faq
- This file (agent-setup/prompt.md): https://voicelabs.now/agent-setup/prompt.md
- API reference: https://voicelabs.now/docs/api-reference
- MCP server: https://app.voicelabs.now/api/mcp
- Pricing: https://voicelabs.now/pricing
- Support: https://voicelabs.now/support