Hypnothera for
AI agents.

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 find a free session in the public library, or 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. Neither requires a Hypnothera account.

The MCP server exposes nine tools. Free and read-only: get_account, list_topics, search_sessions, get_session, list_voices and list_journeys. Spending credits: create_session, continue_journey and render_audio. It does not schedule sessions, delete anything, or change billing. This guide documents MCP and browser handoff; there is no standalone REST API documented here.

The finish line: MCP starts writing a script. Once it has finished, either render it with render_audio after the user approves a voice and the credit cost, or send the user to the returned link to choose their voice and render it on Hypnothera. Do not tell them their audio is ready until get_session shows has_audio.

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

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:

/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 or SKILL.md as context. Reading a skill does not itself connect an account.

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 can choose a voice and render audio there, or approve render_audio once the script has finished.

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

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.

get_account

Read-only. No arguments:

{}

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):

{
  "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 to choose a dialect.
• journey_days — optional integer, 2–30. Creates the first day of a multi-day journey. Create later days with continue_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).

Audio duration is not a tool argument. The voice is chosen when rendering, with render_audio or on the website.

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. For a journey, list_journeys shows each day's script status.

list_journeys

Read-only. Optional journey_id (a collection_id). Without it, returns up to 10 of the account's most recent journeys. Each journey includes journey_id, name, target_days, days_created, next_day, a days array (planned title and description, and the script_id and status of any session created for that day), and the journey's url.

continue_journey

Creates the next planned day of a journey as a follow-up to the previous day's session. Call only after the user asks for the next day, and create one day per request. It spends credits and is not idempotent.

{ "journey_id": "<collection_id>", "notes": "Yesterday felt calmer; focus more on the opening minute." }

• journey_id — required, from create_session or list_journeys.
• notes — optional string, up to 600 characters, in wellness language with no names or identifying details.

It requires a Premium plan and a finished previous day. Otherwise it returns ok: false with a message saying why; do not purchase or upgrade on the user's behalf.

list_topics

Read-only, no arguments. Returns the library's topics as id and label, for example sleep, calm, focus and confidence.

search_sessions

Read-only and free. Searches the public library of ready-made sessions, which play free at their listen_url without an account or credits. Prefer it when the user wants something to play now.

{ "query": "calm before a presentation", "topic": "confidence", "language": "english", "limit": 5 }

All arguments are optional: query (up to 100 characters, every word must appear in the title or description; use topic to filter by theme), topic (an id from list_topics), language, and limit (1–10, default 5). Each result has script_id, title, description, duration_minutes, language and listen_url.

get_session

Read-only. Takes a script_id from search_sessions, create_session or list_journeys. Returns a library session or one of the account's own sessions, with source, status, has_audio and listen_url. Use it to check whether a created script has finished. Once audio exists, audio_url is a direct link that plays for about two hours without signing in.

list_voices

Read-only. Optional language. Returns narrator voices with voice_id, name, gender, accent, language, tier, a preview_url, and available for the connected account's plan. Pass a voice_id marked available to render_audio.

render_audio

Renders one of the account's own finished scripts as audio. It spends about 1 credit per minute of audio and is not idempotent. Before calling it, show the user the voice and the estimated credits, and wait for their approval.

{ "script_id": "<script_id>", "voice_id": "<voice_id from list_voices>" }

It refuses with ok: false and a message when the script is still being written or already rendering, the voice isn't available on the account's plan, the session is longer than the plan allows, or the balance is too low. On success it returns estimated_minutes and estimated_credits. Rendering takes a few minutes; poll get_session until has_audio is true, then share audio_url or listen_url.

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:

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

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.

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.

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.

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.

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. When the user is ready for the next day, call continue_journey with the returned collection_id, or they can continue on Hypnothera.

{
  "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." }
  ]
}

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 it is rendered with render_audio or 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. Each later day is created one at a time with continue_journey (Premium) or on the website, and its script and audio use additional credits. A successful MCP response means script generation has started, not that every journey day or any audio is complete.

See pricing for current plans. Do not purchase credits or change a subscription on the user's behalf as part of this workflow.

• 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. 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 with the user first; the original request may have created a session. There is no idempotency key. get_session shows a returned script_id's status, and for a journey list_journeys shows which days already have a session.
• Script exists but there is no audio: rendering is a separate step. Call render_audio with the user's approval, or open next_step_url to render 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, include the error message and any returned script or task ID. Do not include access tokens, chat logs, or a private handoff URL.