For AI agents
The prompt to give your coding agent, how to connect Cursor, Claude Code or Codex to the two MCP servers, and every machine-readable surface of orgasm.dev.
orgasm.dev is written to be integrated by an agent. There are two kinds:
- Integration-time agents write the integration: they read the docs and the contracts, call the sandbox while they work, and write tests.
- Runtime agents run inside a product and act on a person's session as it happens, through the action MCP server.
The prompt
Paste this into your coding agent from your project:
Integrate orgasm.dev into this project. Read https://orgasm.dev/llms.txt first, then the pages it links that apply. The REST contract is https://orgasm.dev/openapi.json and the events are https://orgasm.dev/asyncapi.json. To call the API while you work, connect the MCP server at https://orgasm.dev/mcp with a test key (any key that starts with sk_test_ reaches the sandbox). Inspect this project's language, framework and where it uses the camera, then choose: - live sessions (POST /v1/live-sessions) for a camera stream, or recordings (POST /v1/recordings) for video files; - server-sent events, the WebSocket or webhooks for the results. Keep the secret key on the server. Have the end user's device generate the capability and publish its front camera and microphone itself; pass only the capability's SHA-256 and the client token across. Set consent only where this product verifies that the person on camera is an adult and has agreed to the analysis; ask me how it does that if you cannot find it. If the product has user accounts, set userReference on each live session to a pseudonymous id for the person: an HMAC of their user id under a key of this product's own, never their email, phone or name. Set clientReferenceId to this product's own id for the session. Our finance team then sees what each user and session cost. Treat imminence as a probability over 30 and 60 seconds, not a countdown, and orgasm calls as arriving a few seconds after the moment they name. If the product changes stimulation, report it with reportStimulation. If it implements edge, ruin or finish, start from the reference presets at https://orgasm.dev/docs/concepts/presets, and keep a stop control that works whatever the signals say. Write tests against the sandbox scenarios (sandbox.scenario, sandbox.speed). Then tell me what you built, how to run it, and what remains before live keys.
Connect your agent
Give your agent both MCP servers: the docs server needs no key, and the action server takes a test key, so every call it makes reaches the sandbox. Any key that starts with sk_test_ works; put it in ORGASM_KEY first:
export ORGASM_KEY=sk_test_your_own_suffixOpen each link to install the server in Cursor, which asks before it does: orgasm.dev actions and orgasm.dev docs. Or add them to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:
{
"mcpServers": {
"orgasm": {
"url": "https://orgasm.dev/mcp",
"headers": { "Authorization": "Bearer ${env:ORGASM_KEY}" }
},
"orgasm-docs": { "url": "https://orgasm.dev/api/mcp" }
}
}Live keys belong on your server, never in an agent's configuration. Get one from your dashboard once you sign up.
Contracts
The two documents are the source of truth; everything on this site is generated from them.
| Document | What it describes |
|---|---|
/openapi.json (YAML) | OpenAPI 3.1: every REST operation, its parameters, bodies, responses and errors. Each operationId is also an MCP tool name. |
/asyncapi.json (YAML) | AsyncAPI 3.1: the events, on the stream, the socket and webhooks, with examples the sandbox actually sends. |
/.well-known/api-catalog | RFC 9727 linkset pointing at both documents and the docs. |
/.well-known/mcp.json | Both MCP servers, how to connect, and their tools. |
Generate a client with any OpenAPI generator. Errors are RFC 9457 problem details whose type links to an explanation of their code (errors).
Docs as Markdown
| URL | Contents |
|---|---|
/llms.txt | An index of every page, one line each. |
/llms-full.txt | Every guide, then the REST reference and the events reference, in one file. |
/docs/<page>.md | One page as Markdown. Charts and tables on a page become Markdown tables. |
Accept: text/markdown | Any docs URL, and /, answers in Markdown when asked (with Vary: Accept). |
Docs MCP server
Lists, searches and reads these docs. No key.
{
"mcpServers": {
"orgasm-docs": { "url": "https://orgasm.dev/api/mcp" }
}
}Tools: list_pages, get_page (by URL) and search.
Action MCP server
Calls the API with your key: one tool per operation, plus two helpers. With a test key every call reaches the sandbox, so an agent can run an integration end to end.
{
"mcpServers": {
"orgasm": {
"url": "https://orgasm.dev/mcp",
"headers": { "Authorization": "Bearer sk_test_your_own_suffix" }
}
}
}| tool | calls | does |
|---|---|---|
| list_live_sessions | GET /v1/live-sessions | Lists your company's live sessions, newest first. |
| create_live_session | POST /v1/live-sessions | Starts analysis capacity for one person's live camera stream and returns where their device publishes (`ingest`) and where events arrive (`results`). |
| purge_live_sessions_by_user_reference | POST /v1/live-sessions/purge | Purges every live session created with this `userReference`, as `purgeLiveSession` does one: each is ended if it is still running, then deleted with all its events. |
| get_live_session | GET /v1/live-sessions/{sessionId} | Returns the session's status, which inputs are arriving, the subject read once it is made, and the latest imminence (`latestImminence`). |
| end_live_session | DELETE /v1/live-sessions/{sessionId} | Ends the session now: the device's connection is closed, a final `session.status` with `endedReason: client_ended` is emitted, and the analysis capacity is released. |
| purge_live_session | POST /v1/live-sessions/{sessionId}/purge | Ends the session if it is still running, then deletes it and all its events now rather than at `resultsExpireAt`, and erases its `userReference`, `clientReferenceId` and metadata from your company's charges, which stay, unattributed. |
| list_live_session_events | GET /v1/live-sessions/{sessionId}/events | Returns the session's events in order, oldest first. |
| create_view_token | POST /v1/live-sessions/{sessionId}/view-tokens | A read-only token for one session's events, for a screen other than the person's device: a heads-up display drawn into a stream, a coach's view, a second monitor. |
| report_stimulation | POST /v1/live-sessions/{sessionId}/stimulation | Tells the analysis when stimulation starts, stops or changes, if your product controls it (a device, an e-stim unit, a scene). |
| list_recordings | GET /v1/recordings | Lists your company's recordings, newest first. |
| submit_recording | POST /v1/recordings | Submits a recorded video for analysis. |
| get_recording | GET /v1/recordings/{recordingId} | Returns the recording's status and progress and, once `completed`, its `result`: the subject read, a summary of each orgasm, and the timeline of discrete events. |
| delete_recording | DELETE /v1/recordings/{recordingId} | Deletes the recording's results and events now and stops processing if it is still running. |
| list_recording_events | GET /v1/recordings/{recordingId}/events | Returns the recording's full event timeline in order, including `imminence.updated` for every second of analysed face. |
| list_webhook_endpoints | GET /v1/webhook-endpoints | Lists your company's webhook endpoints for the key's mode, newest first, without their secrets. |
| create_webhook_endpoint | POST /v1/webhook-endpoints | Registers an HTTPS URL on your server to receive events as POSTs, signed per the Standard Webhooks specification (`webhook-id`, `webhook-timestamp`, `webhook-signature`). |
| get_webhook_endpoint | GET /v1/webhook-endpoints/{webhookEndpointId} | Returns one webhook endpoint and the event types it receives, without its secret. |
| update_webhook_endpoint | PATCH /v1/webhook-endpoints/{webhookEndpointId} | Changes an endpoint's URL, the event types it receives, its description, or whether it is enabled. |
| delete_webhook_endpoint | DELETE /v1/webhook-endpoints/{webhookEndpointId} | Stops all deliveries to the endpoint, including retries in flight. |
| roll_webhook_secret | POST /v1/webhook-endpoints/{webhookEndpointId}/roll-secret | Replaces the endpoint's signing secret and returns the new one, once. |
| send_test_webhook | POST /v1/webhook-endpoints/{webhookEndpointId}/test | Sends one signed sample event of the given type to the endpoint now and reports how your server answered. |
| get_usage | GET /v1/usage | Your company's live-session and recording minutes per day for the key's mode, and the orgasms, ruins, edges and session minimums counted, with the credits they drew (always 0 in test mode). |
| get_credits | GET /v1/credits | Your company's credit balance: what is available, what is left of the 20 free credits, and each package with its price per credit, what it has left and when it expires. |
| list_charges | GET /v1/charges | Every orgasm, ruin, edge and session minimum your company's live sessions were charged for, newest first, with what each cost in US dollars and the session's `userReference`, `clientReferenceId`, metadata and key, so that you can break your costs down by person, by your own session or by any metadata value. |
| list_models | GET /v1/models | The models behind each signal: what each produces, which inputs it needs, who it applies to, and where it is available. |
| get_attestation_policy | GET /v1/attestation-policy | What a device must check in an enclave's attestation before it publishes media: the token issuer, the confidential-computing hardware, the enclave image's source and minimum release, and the sealing scheme. |
| wait_for_event | helper | Waits until a live session or a recording has an event of one of the given types after `after`, for up to `timeoutS` seconds, and returns the matching events with the cursor to continue from. |
| get_latest_imminence | helper | Returns a live session’s newest imminence (p30 and p60, the probability that the next orgasm begins within 30 and 60 seconds), with the session status, the subject read and the last orgasm calls. |
wait_for_event follows a session without a stream client: call it in a loop, passing back nextCursor as after. get_latest_imminence answers "how close is it now" in one call, with the session status, the subject read and the last calls.
API-key management is deliberately not exposed as tools.
Rules for runtime agents
A runtime agent acts on a person in an intimate moment. Build these in:
- Never set
consenton someone's behalf. Only set it when the product has verified the person's age and recorded their agreement. - Treat imminence as a probability over a horizon, never as a countdown, and orgasm calls as a few seconds late.
- Never raise intensity, or take any irreversible action, on a single signal. Prefer cues from a preset, with hysteresis.
- Stop when the person says stop, whatever the signals say, and end the session when the experience ends (
end_live_session). - When someone asks for their data to be deleted, call
purge_live_sessionordelete_recording.
Quickstart
A sandbox live session in five minutes, followed by its events, with curl and with TypeScript.
Credits and billing
What live sessions are charged for and how each charge is counted, where charges show up, what happens at zero, what each of your users and sessions cost, reconciling with your invoices, and testing it in the sandbox.