Setup Host Guides

Use these guides to test and run Voicetta setup from your AI host. The canonical contract is the Setup API 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:

{
  "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:

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

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)

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

Authenticated steps

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:

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

---

Troubleshooting

Related pages

• Agent Setup Playbook
• LLM and MCP Readiness
• Glossary