# Hypnothera: API & AI agents

Hypnothera is a personalized hypnosis app that creates original guided audio around each user's goals, words, preferred voice, and session length.

Canonical guide: https://hypnothera.ai/help/api-and-agents

## Choose your starting point

An assistant can prepare a brief for sleep, relaxation, confidence, focus, a chosen habit, or mental rehearsal for an upcoming event.

- **Connected assistant:** use MCP to check the user's account and create a session script after they approve the brief.
- **Any other assistant:** prepare an approved brief and build a handoff link. The user signs in and continues on Hypnothera.
- **Just exploring:** read this guide or the [session skill](https://hypnothera.ai/skills/hypnothera-session/SKILL.md). Neither requires a Hypnothera account.

The MCP server exposes two tools: `get_account` and `create_session`. It does not expose audio rendering, session search, playback, scheduling, deletion, or billing changes. This guide documents MCP and browser handoff; there is no standalone REST API documented here.

**The finish line:** MCP starts writing a script. The user follows the returned link, chooses their voice and audio settings, and renders the audio on Hypnothera. Do not tell them their audio is ready just because a tool call succeeded.

## Connect through MCP

Use this remote server URL in an MCP client that supports Streamable HTTP and browser-based OAuth:

```text
https://hypnothera.ai/api/mcp
```

Sign in to Hypnothera in the browser and approve the connection. Authentication uses the connected user's account; never ask them to paste a password, browser cookie, or access token into a conversation.

**Claude Code plugin**

The Hypnothera plugin includes the session skill and MCP connection. Run these commands in Claude Code:

```text
/plugin marketplace add La-Salida/hypnothera-skill
/plugin install hypnothera@hypnothera
```

Then run `/mcp`, select **hypnothera**, and choose **Authenticate**. Complete the browser sign-in. Ask the assistant to call `get_account` to verify the connection.

**Other MCP clients**

Add the server URL using your client's remote MCP settings and complete its OAuth flow. Settings and configuration formats vary by client. If your client cannot authenticate this server, use the handoff workflow below; it needs no MCP connection.

**Without installing a plugin**

Give your assistant the [plain Markdown guide](https://hypnothera.ai/help/api-and-agents.md) or [SKILL.md](https://hypnothera.ai/skills/hypnothera-session/SKILL.md) as context. Reading a skill does not itself connect an account.

## From a conversation to a session

1. Ask what the user wants to feel, do, or change. Use only context they want included; a full chat history is unnecessary.
2. Write a short, anonymous brief in the second person. Remove names, employers, locations, diagnoses, and identifying details. Do not copy chat excerpts.
3. Show the exact brief, session type, style, and any journey outline. Explain that creating the script uses a credit and rendering audio costs additional credits. Wait for explicit approval before calling `create_session` or building a handoff link.
4. For MCP, call `get_account` and check the connection and balance. Then call `create_session` once with the approved fields.
5. Read the result. On success, share `next_step_url` and explain that the script is being written. The user chooses a voice and renders audio there.

Hypnothera is a wellness and self-improvement product. Describe relaxation, composure, focus, sleep, or personal goals. Do not promise outcomes or frame a session as professional care.

**A useful first prompt**

```text
Help me prepare for an interview using Hypnothera. Ask what I want to
rehearse, then show me a short anonymous brief and explain the credits
before creating anything. Leave out names and employer details.
```

## Tool reference

### get_account

Read-only. No arguments:

```json
{}
```

Returns `ok`, `email`, `tier`, and `credits` for the connected account. Treat the email as private. Check `ok` before using the result.

### create_session

Starts a private session script on the connected account. Call only after approval. This action spends a credit and is **not idempotent**: repeating it can create another session and spend another credit.

Example tool arguments (these are not a raw HTTP request):

```json
{
  "specific_needs": "You want to feel composed before an upcoming interview. Rehearse pausing before answering, speaking clearly, and returning your attention to the conversation when your mind wanders.",
  "script_type": "visualization",
  "style": "conversational",
  "language": "english"
}
```

- **specific_needs** — required string, 20–2,000 characters. Describe the goal in 2–6 sentences.
- **script_type** — optional: `standard`, `sleep`, `morning`, `nsdr`, `lucid_dreaming`, or `visualization`. Defaults to `standard`.
- **style** — optional: `mindfulness`, `classic`, `conversational`, `storytelling`, `direct`, `experimental`, `nlp`, `energetic`, `rapid`, or `somatic`. Defaults to `mindfulness`.
- **title** — optional string, up to 120 characters. Used to name a journey playlist when `journey_days` is set. It does not set an individual session's generated title; omit it for a single-session MCP request.
- **summary** — optional string, up to 500 characters.
- **language** — optional string, up to 40 characters; defaults to `english`. Unsupported languages return an error. For Arabic, use [Create](https://hypnothera.ai/create) to choose a dialect.
- **journey_days** — optional integer, 2–30. Creates the first day of a multi-day journey.
- **journey_outline** — optional array, at most 30 entries. Supply one per day in order, each with `title` (up to 120 characters), `description` (up to 400), and optional `directives` (up to 400).

Voice and audio duration are not tool arguments. Choose them on the website when rendering audio.

### Read the result

Tool results contain a JSON string in an MCP text content block. Parse that JSON and inspect `ok`; do not equate a successful transport response with a successful generation request.

On success, the result includes `message`, `script_id`, and `next_step_url`. It may include `task_id` and a `collection_id` for a journey. Return the actual `next_step_url` to the user; do not invent a link from example IDs.

On failure, expect `ok: false` with a `message`. A successful start does not prove that background generation or audio rendering has finished. There is no MCP polling tool.

## No MCP? Use a handoff link

This works with any assistant that can produce a UTF-8, base64url-encoded JSON payload. No API credentials are needed to build the link. The user signs in and confirms the brief on Hypnothera before generation.

Use this envelope, rather than the flat MCP arguments:

```json
{
  "v": 1,
  "source": "agent",
  "brief": {
    "specific_needs": "You want to feel composed before an upcoming interview. Rehearse pausing before answering, speaking clearly, and returning your attention to the conversation when your mind wanders.",
    "script_type": "visualization",
    "style": "conversational",
    "language": "english"
  }
}
```

The optional `brief.title` labels the handoff preview and names a journey playlist. It does not set the generated session's title. Do not promise that a proposed title will become the saved session title.

For a journey, add a top-level `journey` object with `days` (2–30) and an optional `outline`. Each outline entry has a `day` number starting at 1, `title`, `description`, and optional `directives`. The MCP fields `journey_days` and `journey_outline` do not belong in this envelope.

After approval, save your payload as `brief.json` and run this Node.js command. It only prints a link; it does not create a session:

```javascript
const fs = require("node:fs");
const payload = JSON.parse(fs.readFileSync("brief.json", "utf8"));
const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
console.log("https://hypnothera.ai/from-skill#" + encoded);
```

Keep the payload after `#`, not in query parameters. Use base64url, not plain base64, and do not encode JSON by hand. Open the complete URL or give it to the user to open.

**A fragment is not encryption.** The brief can be read by anyone with the full link and may remain in browser history or conversation logs. Keep it anonymous and do not put these links in public issue trackers. The browser reads the brief and sends it to Hypnothera when the user proceeds with creation.

## Briefs worth starting with

Use these as starting points. Adapt the words to the user and get approval; do not silently infer sensitive details.

### Rest · put the day down

Use `script_type: sleep` and `style: mindfulness`.

```text
You want to leave unfinished tasks for tomorrow and settle into a quieter
evening. Focus on releasing physical tension, letting thoughts pass
without solving them, and giving yourself permission to rest.
```

### Feel · a steadier start

Use `script_type: morning` and `style: conversational`.

```text
You want to begin the day with steady attention and more self-belief.
Rehearse choosing one manageable priority, starting without needing
perfect confidence, and returning gently when distractions arise.
```

### Change · choose a different response

Use `script_type: standard` and `style: mindfulness`.

```text
You want to spend less of your evening scrolling. Rehearse noticing the
urge to reach for your phone, pausing, and choosing a small activity
that fits the restful evening you want.
```

### Perform · prepare for a conversation

Use `script_type: visualization` and `style: conversational`. Start with the interview example in the tool reference, then ask which moments the user wants to rehearse: opening, answering a difficult question, or taking a pause.

### Build a three-day journey

Add these fields to approved MCP session arguments. Only Day 1 is created initially; the user continues later days on Hypnothera.

```json
{
  "journey_days": 3,
  "journey_outline": [
    { "title": "Find your footing", "description": "Practice settling attention before the conversation." },
    { "title": "Rehearse the moment", "description": "Imagine listening, pausing, and answering clearly." },
    { "title": "Carry it with you", "description": "Rehearse returning to composure when something unexpected happens." }
  ]
}
```

## Credits & completion

Connecting an assistant and reading the skill are free. `get_account` checks the current balance without creating a session.

The MCP tool describes **1 credit per script**, plus **about 1 credit per minute of audio** when the user renders it on the website. A five-minute session is therefore about six credits in total. Check the actual balance and the website's current rendering cost before proceeding; do not promise that signup credits cover a particular session.

A journey creates Day 1 first, not all days at once. Later scripts and audio use additional credits as the user continues. A successful MCP response means script generation has started, not that every journey day or any audio is complete.

See [pricing](https://hypnothera.ai/pricing) for current plans. Do not purchase credits or change a subscription on the user's behalf as part of this workflow.

## When something goes wrong

- **Authentication required or expired:** reconnect through the client's OAuth flow. In Claude Code, use `/mcp` → hypnothera → Authenticate. Verify with `get_account` before another creation request.
- **Insufficient credits:** report the message and link to [pricing](https://hypnothera.ai/pricing). Let the user decide how to proceed.
- **Invalid or unsupported brief:** correct the field mentioned in the error. Show any changed brief to the user for approval before submitting it again.
- **Timeout or interrupted creation:** do not automatically retry `create_session`. Check the [library](https://hypnothera.ai/library) with the user first; the original request may have created a session. There is no idempotency key or MCP tool for checking a previous request.
- **Script exists but there is no audio:** open `next_step_url`. Voice selection and audio rendering are separate steps on the website.
- **Journey returned a session link instead of a playlist:** do not create the session again. Preserve the returned link; the script may exist even if playlist creation did not finish. Contact support if needed.
- **Handoff link cannot be read:** check `v: 1`, a non-empty `brief.specific_needs`, valid JSON, UTF-8 encoding, and the complete base64url fragment after `#`. Rebuild the approved payload instead of editing the encoded text.
- **Client does not support this remote connection:** use the handoff workflow. Installing a skill alone does not add MCP or OAuth support to a client.

If you need [support](https://hypnothera.ai/support), include the error message and any returned script or task ID. Do not include access tokens, chat logs, or a private handoff URL.