# Satie MCP — spatial audio for your world

Remote HTTP endpoint: `https://www.satie.world/mcp`.

<!-- public-facts:start -->
Signup is open. Connect over HTTP MCP with OAuth, then call `satie_status`. Runtime playback needs no account or authoring token.

Compositions and revisions are unlimited. On Free, composing spends credits at the model’s exact cost; on paid plans it is included. Agree on spending before composing. maxCents and the audit quote bound new takes, not the model cost of composition.

- Free: Free; 30 monthly takes as credits; 3 US cents per additional new take. Evaluation only: hear your own world at full quality in your build; shipping needs a paid plan.
- Vibecoder: $9.99 a month; 200 monthly takes as credits; 3 US cents per additional new take. Ship web games earning under $100,000 a year; what you shipped stays licensed if you cross it later.
- Pro: $29 a person a month; 600 monthly takes as credits; 3 US cents per additional new take. Ship anything; audio made while subscribed stays yours after you cancel.
- Studio: $199 a game a month; 2500 monthly takes as credits; 2 US cents per additional new take. Per title: every teammate, a private library, Wwise, FMOD and Unity export, the data clause, an invoice.

The monthly take allowance is granted as credits. Free composition and other metered actions also draw from that balance, so remaining takes depend on other spending.

[Plans, shipping and licensing clarifications](https://www.satie.world/docs/pricing) · [Pricing JSON](https://www.satie.world/developers/pricing.json) · [Capabilities JSON](https://www.satie.world/developers/capabilities.json)

Satie keeps your scene, the takes it buys, the audio files you give it and your playthrough captures, and renders them offline to train its listening model. Your project code, screenshots and links are never used. Paid plans can opt out with satie_training.
<!-- public-facts:end -->

Satie authors an editable sound scene. Your game owns world state and plays approved assets through the runtime. Playback must not depend on an authoring session, and player code must not contain a developer bearer token.

## Connect

### Claude Code

```sh
claude mcp add --transport http --scope user satie https://www.satie.world/mcp
claude mcp login satie
claude mcp get satie
```

Run these in your own terminal, not through the agent: the login opens your browser and needs an interactive shell (asked to run it, Claude Code answers "stdin isn't a terminal"). Inside a running Claude Code session, `/mcp`, then Satie, does the same sign-in. Complete the browser sign-in and Satie consent, then start a new Claude Code session (or run `/mcp`) so the Satie tools load. Then ask Claude Code to call `satie_status` and `satie_setup`; no separate local Satie server, API key or Codex installation is needed. The same tools and runtime work with both clients.

`--scope user` adds Satie across your projects. Use `--scope project` instead to share a token-free `.mcp.json` entry with a team; each developer approves the project server and authorizes their own Satie account. `claude mcp login` requires Claude Code 2.1.186 or later; on older versions, start Claude Code and run `/mcp`, select Satie, and authenticate there. Remote/headless terminals can use `claude mcp login satie --no-browser` and complete the displayed browser flow manually in an interactive terminal. See the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

If Satie is already configured, `add` exits with "already exists": nothing is wrong, skip it. `Needs authentication` means login is still required, not that installation failed. `Failed to connect` is a distinct error: check the URL, service readiness, client version and any organization MCP restrictions. For normal OAuth, do not add an `Authorization` header or paste a token: a stale configured header can prevent Claude Code from falling back to OAuth. Project configs may need interactive approval before a health check runs. Verify success with an actual `satie_status` call, not just the CLI's configuration-added message.

### Codex

```sh
codex mcp add satie --url https://www.satie.world/mcp
codex mcp login satie
codex mcp list
```

Complete interactive sign-in, then call `satie_status` to verify identity, plan and available credits. Client approvals and MCP annotations do not replace spending consent: composition can spend credits on Free. Ask before paid work; `satie_realize` bounds new takes with `maxCents` or the agreed quote. Give the server a longer wait in `~/.codex/config.toml`:

```toml
[mcp_servers.satie]
tool_timeout_sec = 360
```

Website sign-in is not agent authorization. Other clients must support remote HTTP MCP plus OAuth; their configuration formats differ. See the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

The service must return JSON at `/.well-known/oauth-protected-resource` and a 401 discovery challenge for an unauthenticated MCP request. HTML at either endpoint indicates a deployment problem, not a reason to invent a token or bypass authentication. The human onboarding page checks public routing, not your account connection. An OAuth server must be enabled/configured by the Satie operator before login works.

### Cursor, VS Code and other clients

Cursor: open this link, or add the server under Settings, MCP, with the URL `https://www.satie.world/mcp`:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=satie&config=eyJ1cmwiOiJodHRwczovL3d3dy5zYXRpZS53b3JsZC9tY3AifQ==
```

VS Code (Copilot agent mode): `vscode:mcp/install?%7B%22name%22%3A%22satie%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.satie.world%2Fmcp%22%7D`, or add to `.vscode/mcp.json`:

```json
{ "servers": { "satie": { "type": "http", "url": "https://www.satie.world/mcp" } } }
```

Any client that reads an `mcpServers` config (Windsurf, Kiro, Goose, Cline, Zed, Gemini CLI): one entry, no key, no local process:

```json
{ "mcpServers": { "satie": { "type": "http", "url": "https://www.satie.world/mcp" } } }
```

Or let the installer write it for the client you have: `npx add-mcp https://www.satie.world/mcp`.

Claude Code can also take the whole thing as a plugin (server, skill and the sound reviewer agent): `claude plugin marketplace add Attractor-Laboratories/satie-skills` then `claude plugin install satie`.

GitHub Copilot's cloud coding agent cannot sign in to an OAuth MCP server from its sandbox; use Copilot in VS Code, or another client, for Satie.

### Long authoring calls

Composition and realization can take minutes. A call that has saved progress answers after about 45 seconds with `status: in_progress`, inside every client's default tool timeout; repeat the identical call (same arguments and request key) and it resumes where it stopped, nothing finished is redone or re-bought. `satie_run` lists your runs. Do not submit a new paid request because a call paused or the client stopped waiting.

If you prefer one long call, raise the client's wait: Codex `tool_timeout_sec = 360` inside `[mcp_servers.satie]`; Claude Code `MCP_TOOL_TIMEOUT=360000 claude` or `"timeout": 360000` on the server in `.mcp.json` (seconds in Codex, milliseconds in Claude Code).

## The skill and your AGENTS.md

The long-form doctrine (briefing, behavior discovery, the glue per engine, listening and release, recovery) is the `satie-sound-for-worlds` skill. The server serves it over MCP (`skills/list`, `skills/get`) to clients that support the Skills extension, and the same files install into a project for Claude Code, Codex, Cursor, Copilot and Gemini CLI:

```sh
npx skills add Attractor-Laboratories/satie-skills
```

Skills are opened when the agent decides they apply. Rules that must always hold belong in the project's `AGENTS.md`, `CLAUDE.md` or `.cursor/rules`; the `satie_rules` prompt on the server (in Claude Code, `/mcp__satie__satie_rules`) or `satie_setup { topic: "rules" }` prints the section for your engine and origin. This is it:

```md
## Sound (Satie)
Audio for this world comes from the Satie MCP (https://www.satie.world/mcp). Runtime: `npm install https://www.satie.world/runtime/0.4.15/satie-runtime.tgz`.
- Call satie_status first, then the five calls in order: satie_inspect_scene { scene } once with the whole manifest (keep its contractId); satie_brief { brief, contractId } and put its load-bearing questions to the developer; satie_compose { brief, contractId } (revise with the current script); satie_audit_scene { script, contractId }; satie_realize { script, maxCents }.
- Spend rule: briefs, audits and checks are free. Composition is included on paid plans and billed at actual model cost on Free. New takes use credits at the plan price. Ask before spending. maxCents (or confirm: { quoteId } from the audit) bounds new takes, not composition cost; never raise it on your own.
- samples.json: save it from samplesUrl as is (curl -fsSL "$samplesUrl" -o public/satie/samples.json); never transcribe it; only the clipPaths it contains exist. The link lasts one hour; satie_samples { realizeId } signs a fresh one.
- Files: public/satie/scene.satie (the script), public/satie/samples.json (the samples map), public/satie/hosts.json (the host map: object or prefab to host id). Commit all three; keep the `at <id>` host ids stable.
- In development mount the mixer and the "Sound by Satie" badge under the dev flag (satie_setup { engine } has the lines). The badge is the mixer's one door and the mixer is the one place sound is changed: build no sound UI of your own (no mixer, no sound button or panel, no volume sliders or mute toggles for Satie's sounds); a control that changes the world publishes a signal; the developer's edits land in .satie/authoring/ (gitignore it) and come back into the script through Satie, not by hand.
- While the game runs in development, the mixer keeps .satie/now.md current: where the developer stands, what they look at and hear, the loud moments of the last five minutes, their mixer edits, and open requests for you. On any message about the world or its sound ("this", "here", "that noise", "what was that"), read its top 20 lines (At a glance) first and the rest only if those do not settle it; skip it for pure code questions or when it is minutes old. Their words always win over the file. A task in .satie/requests/ ("Satie task: …") says what to do and the exact names to add: set its Status to taken when you start; when finished set Status: done and add a Done: line (one plain sentence) and a Files: line (the files you changed). The mixer holds the game's reload until the developer presses Reload, then puts the sound in. From the start of every session in this project, if you can watch in the background, keep `node node_modules/satie-runtime/watch-tasks.js` running (Claude Code: the Monitor tool, started again when it expires): it prints one line per task the developer sends from the mixer, and you take each at once, unasked. Agents that cannot watch get the task pasted. In Claude Code, Satie's hooks read the context on every message and wake you when a task arrives, with nobody typing: .claude/settings.json `{ "hooks": { "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node node_modules/satie-runtime/now.js" }] }], "SessionStart": [{ "hooks": [{ "type": "command", "command": "node node_modules/satie-runtime/now.js session" }, { "type": "command", "command": "node node_modules/satie-runtime/watch-tasks.js --hook", "asyncRewake": true }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "node node_modules/satie-runtime/watch-tasks.js --hook", "asyncRewake": true }] }] } }`.
- Change scene.satie by splicing: edit only the lines for what you were asked to change, and leave every other line, value and comment as it is (never rewrite, reformat or re-compose the whole file over a mix the developer has tuned). The open game plays your edit at once and the mixer names any value of theirs it changed, with "put mine back"; a level or setting they did not ask about is theirs. While the game is open in development the dev server rebinds the contract when the file changes; otherwise run npx satie-runtime rebind public/satie.
- Binaries (pictures, captures, audio) go through satie_asset, never inline base64. satie_publish stays private. An uploaded capture is rendered for training unless a paid account opted out (satie_training); the developer's own labels (satie_record_*) still need their explicit consent.
```

## First working world

1. Call `satie_status` and `satie_setup` for the actual engine. Read live tool schemas rather than guessing arguments. The maintained browser integrations include Three.js and React Three Fiber, in a flat page or an immersive WebXR session. Unity uses the maintained native package; Godot and Lens Studio use placement loaders (see the platform notes below).
2. Inventory stable object IDs, world scale in metres, camera/listener, transforms, extents, materials, rooms/portals, events and footstep surfaces, states and signals (with units/ranges). Distinguish semantic sound hosts from silent visual decoration. Include screenshots when useful, but do not infer unseen geometry as a measurement.
3. Call free `satie_inspect_scene`. Fix missing contract information before generation.
4. Call free `satie_brief` with the brief and manifest you intend to compose from. It lists what the brief leaves open (vantage, enclosure, ground, events and surfaces, what must stay audible, what sounds at once) with what Satie would assume. Put the load-bearing questions to the developer a few at a time and fold the answers into the brief before spending.
5. For an existing approved scene, use `satie_integrate` with the existing script, preserve mode and the returned resume checkpoint. For creative changes, provide the current script and a precise brief to `satie_compose`. Ask before paid work: `maxCents` caps new audio generation. Compositions and revisions are unlimited. Composition spends credits at model cost on Free and is included on paid plans. Pass the current script to preserve approved work.
6. Run free `satie_audit_scene`. Use approved existing files and appropriate library recordings first. Do not add sounds to silent objects or regenerate a whole mix to repair one take.
7. Realize only the authorized missing assets. `satie_realize` returns `samplesUrl`, a signed one-hour link to the finished samples.json (`expiresAt` says when it lapses; `satie_samples { realizeId }` signs a fresh one for a past realization you own, free): save it as is (`curl -fsSL "$samplesUrl" -o public/satie/samples.json`) rather than transcribing the map. Persist the script, contract, sample manifest, exact SHA-256 asset identities, runtime version and renderer settings. A sample URL is not an immutable asset identity. If realize reports takes that need more credits, ask the developer to add credits from the account menu, then call `satie_realize` again with the same script and a new `requestKey`: takes already bought come back free from the reuse pool and only the missing ones are bought. Repeating the identical call only replays the finished result.
8. Use the maintained adapter returned by setup/integrate. Bind each source to its host, update the listener and hosts every frame, fire positional gameplay events, and send states/signals. Start audio only from an explicit user gesture. Stop/dispose the engine when the player unmounts.
9. Capture a representative route with `beginCapture`/`endCapture` and run `satie_audit_playthrough`. A capture too large to pass inline (a few MB is normal) goes up once through `satie_asset` with kind `capture` and is audited by its `captureId`. Exercise every event, source movement and room boundary. Report unexercised paths honestly; runtime success is not calibrated acoustic accuracy or a human listening verdict.
10. Offer the developer the local editor to refine the result. Preserve conditioning context, rejected revisions and actual human preferences with the exact assets/configuration being judged.

## WebXR, Unity, Godot and Lens Studio

Human-readable setup guides for every maintained integration are at [Documentation](https://www.satie.world/docs). Use `satie_setup` and the live export result for exact installation commands and scene-specific capability losses.

**WebXR (a headset in the browser).** The Three.js adapter works inside an immersive session. `satie_setup { topic: "xr" }` covers the rig, listener, animation loop, starting audio on the Enter VR gesture, controller hosts and session visibility. `examples/webxr-starter` is the working starter. It has been checked with an emulated Quest 3, not a physical headset.

**Unity.** After realization, call `satie_export` with engine `unity` and run its returned install command from the project root. This installs `Packages/world.satie.unity`, the recordings and the compiled scene in `Assets/Resources/SatieCore`. Press Play; the package starts automatically. Window → Satie → Mixer edits the running scene; the installer's watch mode applies saved edits and reloads it. The portable core handles distance, room reverb and stated occlusion; Unity panning or the project's spatializer provides direction. Per-voice DSP, movement paths, entities and geometric wall occlusion are not carried. Packaged native libraries currently use rendered synth takes rather than live synthesis. The package has been exercised in Unity 6000.0 on macOS; Windows x64, Linux x64 and Android arm64 libraries are built and symbol-checked, but target gameplay validation is still required. See the [Unity guide](https://www.satie.world/docs/unity).

**Godot.** Export with engine `godot`, download the files, and register `satie/satie.gd` as the `Satie` autoload. It plays the placement manifest with Godot's own audio players. It carries takes, hosts, positions, levels, distance, recurrence, events, surface banks, state gates and supported `follow` controls. Room reverb, occlusion, per-voice effects, paths, entities and the editor mixer are not carried. The loader has run headless on Godot 4.5. See the [Godot guide](https://www.satie.world/docs/godot).

**Lens Studio.** Export with engine `lens-studio`; the returned TypeScript loader and scene module go with the recordings in the Lens project. Assign the recordings to Tracks and bind the listener and host objects. Live synth output is available through AudioOutput with distance-driven level but no direction; use rendered takes when positioned synth playback is needed. Recorded pitch, room reverb, occlusion, per-voice DSP, paths, entities and the mixer are not carried. Lens Studio 5.15.4 preview on macOS has been exercised; Spectacles hardware has not. See the [Lens Studio guide](https://www.satie.world/docs/lens-studio).

For every export, read `notCarried` and listen in the actual target before relying on feature parity. A successful integration check is not a perceptual verdict.

## Privacy, rights and cost

- Do not call paid tools without the developer's approval. Read the live returned estimate/budget scope. `satie_status` says who pays in one object: `billing.mode` (metered or unmetered), `billing.balanceCents`, `billing.allowance` and `billing.whoPays` (developer or satie); an unmetered account has no balance to watch and Satie pays for its takes.
- Keep credentials in the agent or local server environment, never browser variables, source archives, logs or committed MCP config.
- Public examples are playable only after their release is approved. Their source archive contains approved asset references/hashes and available attribution, not private experiment logs. Generated audio is not automatically CC0.
- `satie_publish` publishes a Satie sketch/layout, not arbitrary Three.js application code. Deploy an application's visuals through its normal web build.
- `satie_picture` composes a scene from a photograph. The picture (inline, at most 3 MB, or uploaded first with `satie_asset`) is kept privately under the caller's account and sent to Satie's vision model. It becomes public only when a sketch whose script carries its `# @picture` line is published with `satie_publish`. Use only pictures the developer may share with Satie.
- A local capture is not an upload: nothing leaves the project until `satie_asset` keeps it. An uploaded capture is rendered offline for training unless a paid account opted out; see "Training data" below.

## Training data (2026-11-08)

Satie keeps your scene, the takes it buys, the audio files you give it and your playthrough captures, and renders them offline to train its listening model. Your project code, screenshots and links are never used. Paid plans can opt out with satie_training.

That is the whole disclosure; your agent relays it once, with the first `satie_realize`, and `satie_status` repeats it in one line. The Free plan contributes as a condition of the plan. On Vibecoder, Pro or Studio, `satie_training { action: "opt_out" }` stops new render jobs and cancels queued ones; `"opt_in"` reverses it; already rendered episodes stay unless you ask us to purge them (mateo@attractor.world). Your own believability labels (`satie_record_episode`) and authoring histories (`satie_record_authorship`) are separate and still need your explicit consent. See the [public plan and policy summary](/docs/pricing); contact Attractor Labs for the applicable full service terms.
- `satie_record_authorship` preview is not contribution. Show the sanitized preview; contribute only with explicit consent and the unchanged reviewed-content hash. Do not infer a human “keep” label from a successful build or agent judgment.
- Preserve renderer configuration when recording evaluations. Do not label automatic-level-anchor diagnostic traces as calibrated measurements.

## Examples

Visit [Three.js worlds in Explore](https://www.satie.world/explore/three-js): courtyard (moving cart/events), night street (traffic/state), campfire (wind/fire signals). Explore also has categories for Gaussian splat worlds and community soundscapes. Adapt their host/event interface to the actual game, rather than copying coordinates blindly. The [developer page](https://www.satie.world/developers) links the current onboarding and service checks. Old `/examples` links redirect into Explore.

## Listen before release

Use `satie_listen` for actual isolated takes and recordings of gameplay, not just their
prompts. Submit mono/stereo 16-bit PCM WAV (8–48 kHz, <=30 seconds) with the brief and timed
route. It is free through the MCP and returns an agent judgment; inconclusive listening stays unreviewed.
Review harshness, synthetic artifacts, source fit, repeated texture and foreground/background
balance at spawn, close/far approaches, material transitions and collisions. Missing listening
is `unreviewed`; integration cannot call unreviewed assets ready.

Use `satie_review_release` to check exact-hash take decisions, the current script/assets
revision, all declared route cases, runtime results and measured peak/LUFS limits. Save its
rejection reasons locally and use them in the next compose brief. Replacing audio or changing
a mix invalidates route evidence. This checks supplied evidence and never invents human
approval, publishes a world, or contributes training data.

Hash downloaded asset bytes before decoding. If a take is converted to WAV for listening,
retain both the original asset hash and the audition hash with the conversion settings.
The listener returns the WAV hash; attach that evidence to the verified original asset's
decision. Do not substitute one hash for the other or attach a verdict to unverified bytes.

Bind the real geometry of extended sources with `SatieScene.bindLine(id, object, localPoints,
width)`. `CharacterMotor` is an optional kinematic contact helper; existing physics engines
can supply their own resolved movement/material/depth/impact events. `step(surface)` uses
the current listener position. Keep player step templates free of an unrelated `within`
origin filter. Choose a fixed `levelAnchorDb` from rendered routes, preserving near-source
headroom rather than normalizing from the spawn pose.


Call recovery: compose/world/integrate/realize return runId and send progress every five seconds (notifications/progress when the client sends a progress token, otherwise informational logs). A call never runs into the platform's 300-second limit: when its time budget runs out it saves its progress and returns status in_progress. Then repeat EXACTLY the same call (same arguments and requestKey) right away: it resumes from the checkpoint, and finished stages and bought takes are not redone or re-bought. Repeat until the status is final; a run that makes no progress on two consecutive attempts fails and keeps its checkpoint. After a client timeout call satie_run (omit runId to list recent runs) or repeat the identical call: completed results replay without spending, a live call is not duplicated, and a call whose server died resumes after six minutes. Default requestKey is a stable argument hash; use a new key only for an intentional new paid attempt, and never change the arguments to retry. Ordinary pooled takes are reusable; unique or explicitly replaced takes can cost again. Recovery lasts seven days. Never keep blindly retrying composition with new keys. status.billingMode distinguishes metered, unmetered, unknown; a null balance alone is ambiguous.

Listening corrections: satie_listen accepts up to three rejected WAV references plus the actual human/agent reason (combined audio payload is bounded). Feed the objection and audible counterexample into the next review and composition brief. It returns exact conditioning hashes. A model may accept a bad sound: preserve known human rejections by exact asset hash, and do not erase them with a later model pass. Reference-conditioned rejection of a known example is regression coverage, not evidence of held-out generalization or trained model improvement.

Host lifecycle: publish listener/object transforms before starting. A missing host or excess class-count voice stays silent until its own slot exists; unbind despawned objects. Keep manifest clip keys unchanged (including Audio/). Load first, unlock/resume AudioContext inside the input gesture, and handle re-entry/tab suspension separately from asset readiness. If audio is essential, do not unlock gameplay while it is still loading.

The listening tool describes the recording blindly before comparing it with your brief. Inspect both `heard` and `assessment`; an expected label in the latter is not independent audible evidence. Retain the audio, intent and reviewer identity with the result.

## Pricing and local edits

Integration checks cost no credits. Composition and new takes follow the generated plan facts above. Shipping needs the appropriate paid plan and the applicable recording and runtime licenses; Free is evaluation only. Studio is billed per game. See [plans and usage](/docs/pricing) for allowances, feature gates and unresolved licensing questions.

After editing an existing `scene.satie`, run `npx satie-runtime rebind public/satie` with runtime 0.4.3 or later. This local command checks syntax and required sample keys and refreshes the contract hash and revision without server calls. New prompts need supplied or realized assets first. Previous listening evidence belongs to the previous revision. Runtime checksum and audio hash verification stay enabled.

Zones are allow lists: matching states play unchanged. For beds that duck while reading, declare `normal` and `reading`, use `zone normal` on the beds, and call `state('reading', 0.7)` to muffle them; `zone reading` would do the opposite. For exact volume-only ducking, drive a declared signal through `volume follow`. Host ids may contain dots, for example `pod.week01`.
