---
title: "Setup Host Guides"
description: "Platform-specific guides for provisioning Voicetta via Claude MCP, Cursor MCP, ChatGPT Actions, and raw REST."
publishedAt: "2026-07-15"
modifiedAt: "2026-07-15"
category: "LLM"
tags: "Voicetta, MCP, Claude, Cursor, ChatGPT, REST, E2E"
navOrder: "95"
canonical: "https://voicetta.com/docs/setup-host-guides"
---

# Setup Host Guides

Use these guides to test and run Voicetta setup from your AI host. The canonical contract is the [Setup API playbook](/docs/agent-setup-playbook); each host is a thin adapter.

## Why it matters for your business

- **Save money:** validate one flow once, reuse across Claude, Cursor, and ChatGPT.
- **Work faster:** copy-paste configs per host instead of rediscovering endpoints.
- **Standardize service:** every host follows the same consent → handoff sequence.
- **Delight every Guest:** consistent handoff regardless of which AI tool they use.

## Prerequisites

- Setup API base: `https://api.voicetta.com/v1/setup`
- OpenAPI: https://voicetta.com/setup-openapi.json
- Terminology: **Connection (UI) = Setup Tool (API)**

---

## Claude Desktop (MCP)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "voicetta-setup": {
      "command": "npx",
      "args": ["-y", "@voicetta/setup-mcp"],
      "env": {
        "VOICETTA_SETUP_API_URL": "https://api.voicetta.com",
        "VOICETTA_SETUP_SESSION_ID": "ses_REPLACE",
        "VOICETTA_SETUP_ACCESS_TOKEN": "setup_REPLACE"
      }
    }
  }
}
```

### E2E scenario

1. Ask Claude: "Provision Voicetta for my hotel using voicetta_create_setup_session."
2. Open the returned `consent_url` in a browser and authorize.
3. Paste `session_id` and `setup_access_token` into MCP env (or ask Claude to continue via REST).
4. Run profile, assistant, knowledge, phone, tools, test, and handoff tools in order.
5. Verify handoff includes `login_url`, `voicetta_phone`, and `forwarding`.

---

## Cursor (MCP)

Add to `.cursor/mcp.json` in the project or global Cursor MCP settings:

```json
{
  "mcpServers": {
    "voicetta-setup": {
      "command": "npx",
      "args": ["-y", "@voicetta/setup-mcp"],
      "env": {
        "VOICETTA_SETUP_API_URL": "https://api.voicetta.com"
      }
    }
  }
}
```

### E2E scenario

1. Prompt: "Create a Voicetta setup session with partner_agent cursor."
2. Complete consent in browser when given `consent_url`.
3. Set `VOICETTA_SETUP_SESSION_ID` and `VOICETTA_SETUP_ACCESS_TOKEN` in MCP env.
4. Ask Cursor to list the tool catalog, select `guesty` and `sms`, enable each, then fetch handoff.
5. Confirm envelope `status` is `completed`.

---

## ChatGPT (GPT Actions / OpenAPI)

Import https://voicetta.com/setup-openapi.json as a custom GPT Action. Set authentication to **Bearer** with the `setup_` token after human consent.

### E2E scenario

1. Upload or link the OpenAPI spec to a GPT.
2. Instruction: "Follow the Voicetta agent setup playbook. Start with POST /v1/setup/sessions."
3. When `human_required` appears, show the URL to the user and wait.
4. Continue with Bearer auth for remaining endpoints.
5. End with GET `/v1/setup/sessions/{id}/handoff`.

---

## Raw REST (curl)

For agents without MCP or Actions — including custom or regional LLM hosts.

### Create session

```bash
curl -sS -X POST "https://api.voicetta.com/v1/setup/sessions" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Agent: custom" \
  -d '{"partner_agent":"custom"}'
```

### List tool catalog (no auth)

```bash
curl -sS "https://api.voicetta.com/v1/setup/tools/catalog?category=PMS"
```

### Authenticated steps

```bash
export SETUP_TOKEN="setup_..."
export SESSION_ID="ses_..."

curl -sS "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}" \
  -H "Authorization: Bearer ${SETUP_TOKEN}"

curl -sS -X POST "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}/profile" \
  -H "Authorization: Bearer ${SETUP_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"profile":{"business_name":"Demo Hotel","industry":"Hospitality"}}'

curl -sS "https://api.voicetta.com/v1/setup/sessions/${SESSION_ID}/handoff" \
  -H "Authorization: Bearer ${SETUP_TOKEN}"
```

### E2E checklist

- [ ] `POST /sessions` returns `consent_url`
- [ ] After consent, Bearer token works on `GET /sessions/{id}`
- [ ] Profile, assistant, knowledge steps advance `status`
- [ ] `GET /tools/catalog` lists `guesty`, `sms`, `calcom`
- [ ] `POST /tools/select` and `/tools/{id}/enable` return envelope or `human_required`
- [ ] `GET /handoff` returns login, phone, and next steps

---

## Automated route checks (CI)

Backend pytest verifies Setup API routes are mounted and the public catalog responds:

```bash
cd voicetta-backend-app
poetry run pytest tests/test_setup_api_routes.py -q
```

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `401` on session steps | Missing or expired `setup_` Bearer token |
| `400` state transition | Call steps in order; check `message_for_user_agent` |
| MCP tool returns path error | Set `VOICETTA_SETUP_SESSION_ID` for `/sessions/current` mapping |
| Tool enable returns `human_required` | Send human to the URL; poll session or webhook |

## Related pages

- [Agent Setup Playbook](/docs/agent-setup-playbook)
- [LLM and MCP Readiness](/docs/llm-and-mcp-readiness)
- [Glossary](/docs/glossary)