# Assist With Music agent guide

Updated: 2026-08-14

Assist With Music is the user's durable music-creation workspace. It stores projects, song plans, source/research notes, lyric drafts, prompt attempts, generation attempts, source checks, version review state, and genre context.

What Assist With Music is:
- a private planner for AI-assisted music creation;
- a public genre encyclopedia that can inform style and prompt recipes;
- the durable memory layer where assistants should save structured creation work.

What Assist With Music is not:
- it is not a replacement for an assistant's reasoning, web research, or browser tools;
- it is not a copyright authority;
- it does not operate Suno or other external accounts by itself in V1.

Account and auth:
- private planner data requires a signed-in Assist With Music account through Clerk;
- signing in IS the approval. Completing the OAuth flow gives this connection the default tier on its first call: music:read, music:write, queue:read, queue:work. Nothing else has to be pressed. OAuth still only proves who you are — a Music grant decides what you may do, and the server re-reads that grant on every call — but the sign-in now writes that grant rather than waiting for a second button somebody did not know about;
- four authorities signing in never grants: music.media.read, music.media.write, music:archive, and credit:spend. The owner raises them at https://assistwithmusic.com/settings/ai, which also narrows a connection; it is a dial, not a turnstile. If a call is refused for scope, that is the page to name — signing in again will not change it. Refresh the tool list after the owner changes a grant;
- one authority no approval can grant at all: adding to the owner's Queue. Their Queue is the list of what they asked for, and a connected AI answers it rather than adding to it. Use songplanner_suggest for anything you think they might want; it lands in Ideas at https://assistwithmusic.com/ideas with your reasoning attached, and becomes Queue work only if the owner confirms it there;
- connecting takes minutes, not seconds, and two steps cannot be delegated: signing in, and clicking Allow;
- Music scopes: music:read (read selected records), music:write (save reviewed work and file ideas), music.media.read (bounded private-media reads), music.media.write (guarded private-media ingest), music:archive (permanently remove an empty project), queue:read, queue:work, and credit:spend (external generation preparation only). queue:create is reserved and no connection may hold it;
- no scope permits deleting songs, lyrics, research, prompts, or albums, nor bulk export, publishing, distribution, purchase, payment, accepting terms, or sending messages. The single permanent removal any connection can perform is an empty project under music:archive;
- grants expire, and the owner can revoke one client or all of them at any time; revocation stops discovery and calls immediately and releases any Queue work the client was holding;
- clients must not choose owner/user IDs;
- backend functions derive ownership from the authenticated caller;
- the canonical remote MCP server is LIVE at https://assistwithmusic.com/mcp — connect an MCP client there, sign in over OAuth, and the tools operate on your own private planner data.
- https://thesongplanner.com/mcp remains a direct transport compatibility route for existing clients; new connections should use the canonical Assist With Music URL.
- modern MCP 2026-07-28 requests are self-contained: server/discover replaces initialize, OAuth identity is checked on every request, and no MCP session ID carries owner identity or workflow state;
- existing initialize/session clients remain supported during rollout; this does not claim every named client already uses MCP 2026-07-28.

Connect your AI agent (canonical connector URL: https://assistwithmusic.com/mcp):
- Assist With Music connects to any MCP client that speaks Streamable HTTP with OAuth. Setup below is described by the shape of the client, because that is what we can state accurately.
- Music has not yet recorded a completed connection lifecycle for any named client. The clients named below are examples of each shape — not a claim that Music has run them.
- Clients with a connector settings screen (examples of this shape: Claude, ChatGPT, Cursor): Open the client's settings and find its connectors or MCP section. Add a custom connector and paste the connector URL. Continue, sign in to Assist With Music, and approve the scopes you want to grant. If the client caches its tool list, refresh it once the grant is in place.
- Clients you configure from a terminal (examples of this shape: Claude Code, Codex): Register the connector with your client's MCP add command. Leave the Authorization header off — omitting it is what triggers the OAuth sign-in. Run your client's authenticate or login step and approve the scopes. Refresh the tool list once the grant is in place. Command template: <your CLI> mcp add --transport http assistwithmusic https://assistwithmusic.com/mcp
- the owner approves scopes at https://assistwithmusic.com/settings/ai, and revokes there too.

First workflow:
1. Open /planner and sign in.
2. Choose the project that owns the song idea.
3. Create or open a song plan in the Agent creation workspace.
4. Save research notes, lyric drafts, prompt attempts, and generation attempts as structured records.
5. Use the existing planner table to review generated versions and album picks.

Creation modes:
- exact-public-domain: preserve public-domain lyrics exactly when that is the goal.
- adapted-public-domain: adapt or transform public-domain lyrics.
- scripture-idea: create from scripture, themes, or ideas.
- original: create a complete original song.

MCP production and release tools (generated from convex/mcp.ts; 33 are deployed and callable today, while 3 private-media tools are marked PRODUCTION PENDING until the Convex deploy and operational proof; call songplanner_context with action "workspace" first; use songplanner_loops discover when a task may benefit from the public loop library; prefer the 13 v2 tools; 19 compatibility tools are labeled LEGACY):
- songplanner_get_workspace_context — [LEGACY — use songplanner_context] Deprecated legacy orientation tool; prefer songplanner_context action='workspace'. Returns the signed-in user's projects + recent song plans + creation modes in one read. Legacy projects, recentPlans, and counts map to the v2 fields with the same names. Kept for compatibility.
- songplanner_list_projects — [LEGACY — use songplanner_context] Deprecated legacy project-list tool; prefer songplanner_context action='projects'. Lists the user's projects (key + name + config); legacy projects maps to the v2 projects field. Kept for compatibility.
- songplanner_get_project_context — [LEGACY — use songplanner_read] Deprecated legacy project read; prefer songplanner_read action='project'. Loads one project's plans and child previews before editing. In each legacy plan, research/lyrics/prompts/generations map to v2 childPreview.researchNotes/lyricDrafts/promptAttempts/generationResults. Kept for compatibility.
- songplanner_get_song_plan_context — [LEGACY — use songplanner_read] Deprecated legacy plan read; prefer songplanner_read action='plan' or action='brief'. Loads one song plan and capped child records. Legacy research/lyrics/prompts/generations/sourceChecks map to v2 children.researchNotes/lyricDrafts/promptAttempts/generationResults/sourceChecks. Kept for compatibility.
- songplanner_get_genre_recipe — [LEGACY — use songplanner_context] Deprecated legacy genre recipe read; prefer songplanner_context action='genre_recipe'. Legacy recipes maps to the v2 recipes field. Looks up genre style ingredients; use traits + production language, never a protected artist's identity. Kept for compatibility.
- songplanner_context — Preferred v2 orientation and public genre-discovery tool. Use action='workspace' first for account, projects including config.direction when present, autonomy ceiling, creationCapabilities, capabilityDemand by queue item, runnableOwners, recent plans, and indexed queue funnel counts. action='capabilities' returns runtime boundaries and Queue handoff surfaces. Genre workflow: action='genres' lists top levels; 'genre_families' with name lists that genre's families; 'genre_subgenres' with a returned stable path lists direct children; 'genre_search' with query returns concise ranked candidates from a bounded public encyclopedia scan; then call 'genre_recipe' with name equal to one exactReaderName (or names[] for a batch) for rich depth. Before creative work read direction: avoid is hard, while useSparingly is deliberate and infrequent, never the default. Stamps agentLastActiveAt.
- songplanner_read — Preferred v2 read tool. Use action='brief' for durable memory + resume anchors and full projectDirection, action='plan' for a paginated bounded plan read with projectDirection, and action='project' for config plus direction and a capped overview. Read one plan by planId, its short owner-scoped queueNumber (spoken as Queue 42), compatibility queueRef, or projectKey+planKey. Plan researchNotes return the current note/document plus kind, contentClass, sources, currentVersion, and append-only revision metadata. Other plan children are lyricDrafts, promptAttempts, generationResults, and sourceChecks.
- songplanner_status — Preferred v2 status/provenance tool. Use action='agent_status' to confirm connection, last-active time, runnableOwners, and effective autonomy ceiling; use action='runs' for recent self-reported agentRuns.
- songplanner_loops — Preferred read-only Music Loops & AI Skill Library tool. Use action='discover' early when a creative or planning task may benefit from a repeatable Music workflow; search by task/theme/workflow and optional stage/status. Results are bounded public-library summaries with suitability, capability needs, skill names, stable slugs, and canonical links. Then use action='read' with one returned slug for bounded steps, skill guidance, outputs, and loop relationships. Empty searches and missing slugs are explicit; this is not a raw catalog export and it never reads or changes planner records.
- songplanner_upsert_song_plan — [LEGACY — use songplanner_save] Deprecated legacy plan write; prefer songplanner_save. Creates or updates a song plan idempotently on projectKey+planKey. Kept for compatibility.
- songplanner_write_research_note — [LEGACY — use songplanner_save] Deprecated legacy research write; prefer songplanner_save with researchNotes[]. Saves one research note idempotently on planId+sectionKey. Kept for compatibility.
- songplanner_upsert_lyric_draft — [LEGACY — use songplanner_save] Deprecated legacy lyric write; prefer songplanner_save with lyricDrafts[]. Saves one lyric draft idempotently on planId+draftKey. Kept for compatibility.
- songplanner_upsert_prompt_attempt — [LEGACY — use songplanner_save] Deprecated legacy prompt write; prefer songplanner_save with promptAttempts[]. Saves one prompt attempt idempotently on planId+attemptKey and returns non-blocking project direction warnings. Kept for compatibility.
- songplanner_log_generation_attempt — [LEGACY — use songplanner_save] Deprecated legacy generation-result write; prefer songplanner_save with generationResults[]. Logs a generated result idempotently on planId+attemptKey. Kept for compatibility.
- songplanner_log_source_check — [LEGACY — use songplanner_save] Deprecated legacy source-check write; prefer songplanner_save with sourceChecks[]. Records provenance idempotently on planId+checkKey. Kept for compatibility.
- songplanner_save_creation_result — [LEGACY — use songplanner_save] Deprecated legacy one-call save; prefer songplanner_save. Writes the plan + children + run record in one approval, idempotent on natural keys, with non-blocking project direction warnings for prompts. Per-call child limits, and going over REFUSES the whole call rather than trimming it — nothing is saved, so it is safe to retry split: researchNotes 20, lyricDrafts 10, promptAttempts 10, generationAttempts 20, sourceChecks 20. This tool has no decisions argument and no mutation envelope; songplanner_save has both. Kept for compatibility.
- songplanner_save — Preferred v2 fat save. Writes a plan plus optional decisions, research notes/documents, lyric drafts, prompt attempts, generation results, source checks, run metadata, and up to 20 already-committed mediaIds in one approval. Media IDs attach to the saved plan and add the separate music.media.write requirement. Optional plannerSong materializes and links the finished lyrics as an owner-scoped normal Planner song, using plannerSong.lyricsMarkdown or the last lyricDraft in the same call. A generation result with saveToPlanner:true, externalId, and audioUrl or sunoUrl also materializes that external take as a Planner version; this records completed generation but never starts Suno or spends credits. A prompt-only save returns the plan queueVersion plus generationGate: accounts capped at prep get needs_owner_action and the connected AI must stop before begin_generation or the Suno Create click; delegated agents lacking credit:spend get gateReason delegated_without_credit_spend with autonomyCeiling null; songplanner_read also returns queueVersion for a later approved handoff. researchNotes accepts kind note|document, contentClass source_fact|inference|creative_idea|generated_draft, markdown, and sources; real changes append a revision attributed to the acting agent principal, while identical retries are idempotent. Prompt conflicts with project direction never block the save and return directionWarnings with hard avoid or soft useSparingly tiers. Requires expectedVersion and one client-generated operationId, like the Queue tools: use expectedVersion 0 for a plan that does not exist yet, otherwise the queueVersion a read returned, and reuse the same operationId to retry so the save replays rather than writing a second history. Per-call child limits, and going over REFUSES the whole call rather than trimming it — nothing is saved, so it is safe to retry split: decisions 20, researchNotes 20, lyricDrafts 10, promptAttempts 10, generationResults 20, sourceChecks 20, mediaIds 20. Omitted arrays are untouched; selected/reviewed/parked/published plans are not downgraded. Public-domain assertions require a checked sourceCheck in the same call or already logged on the plan; this is name/url-level source evidence, not a semantic public-domain judgment.
- songplanner_organize — Preferred v2 organization tool. Use action='upsert_project', 'move_plan', 'set_album_stage', owner-only 'set_autonomy', or 'delete_project'. set_autonomy requires ceiling prep|generate|distribute plus userInstruction containing the user's explicit verbal direction; distribute remains unavailable while full-pipeline autonomy is in testing. move_plan accepts planId or fromProjectKey+planKey; toProjectKey='singles' resolves the owner's marker-identified Singles home. upsert_project accepts validated config.direction and merges partial fields without clobbering siblings; exampleArtistIds may reference only the owner's private userResearch artist IDs. Set direction only when the user asked. Album stage is stored in the typed project distributionStage field. delete_project is empty-only. Submitted/released album stages are ceiling-gated and return needs_approval when the user has not allowed distribution.
- songplanner_upsert_project — [LEGACY — use songplanner_organize] Deprecated legacy project organizer; prefer songplanner_organize action='upsert_project'. Creates or updates a project idempotently on key; validated direction is additive and should only be set when the user asked. Kept for compatibility.
- songplanner_move_plan — [LEGACY — use songplanner_organize] Deprecated legacy move tool; prefer songplanner_organize action='move_plan'. Moves a song plan to another project. Kept for compatibility.
- songplanner_list_requests — [LEGACY — use songplanner_queue] Deprecated legacy queue read; prefer songplanner_queue action='list'. Preserves legacy updatedAt-desc open request membership/order. Kept for compatibility.
- songplanner_claim_request — [LEGACY — use songplanner_work] Deprecated legacy exact-plan claim; prefer songplanner_work action='claim' for new runs. Claims the provided planId and preserves legacy behavior. Kept for compatibility.
- songplanner_complete_request — [LEGACY — use songplanner_work] Deprecated legacy completion tool; prefer songplanner_work action='complete'. Marks a claimed request done while preserving legacy output. Kept for compatibility.
- songplanner_report_blocked — [LEGACY — use songplanner_work] Deprecated legacy park tool; prefer songplanner_work action='park'. Records blocked/waiting state and resume anchors while preserving legacy behavior. Kept for compatibility.
- songplanner_list_deferred_work — [LEGACY — use songplanner_work] Deprecated legacy deferred-work read; prefer songplanner_work action='list_deferred'. Lists parked-pending work and resume anchors. Kept for compatibility.
- songplanner_work — Consolidated Queue work tool. Target one owner-scoped item by planId or its short queueNumber from songplanner_queue; queueRef remains an opaque compatibility option. Use claim, heartbeat, unclaim, begin_generation, park, fail, retry, complete, or list_deferred. complete may attach up to 20 already-committed mediaIds to that Queue item and then additionally requires music.media.write. Every targeted response echoes queueNumber, queueLabel (for example Queue 42), queueHref, and compatibility queueRef. An AI may not clear a human gate. Pass current expectedVersion and one client-generated operationId on mutations; reuse one runKey throughout a claim. Suno/browser steps remain desktop-only.
- songplanner_queue — Consolidated Queue tool for work the owner asked for. Actions: list, activity, edit, reorder, discard. You cannot add to the Queue — the Queue is the owner's own list of what they requested, and a connected AI answers it rather than adding to it. Use songplanner_suggest for anything you think they might want; it lands in Ideas and only becomes Queue work if they confirm it. list responses include one stable owner-scoped queueNumber, queueLabel (for example Queue 42), and queueHref; use planId or queueNumber for activity/edit/reorder/discard. Numbers are assigned once from a private per-owner sequence, never expose another owner's count, are never reused, and remain on Done/discarded rows. Opaque MUS-Q queueRef values remain only for old-client/link compatibility. discard removes only the handoff, not creative work. Mutations require expectedVersion and operationId. For explicitly standalone work use targetProjectKey='singles'.
- songplanner_suggest — File your own ideas for the owner: anything you think they might want that they did not ask for. Actions: suggest (entries, each needing suggestionKey, title, and a reason the owner can judge without rebuilding your thinking), list, withdraw. Nothing filed here is queued. It lands on the owner's Ideas page at https://assistwithmusic.com/ideas, attributed to your connection, and becomes Queue work only if the owner confirms it there — confirm and dismiss are theirs alone and no tool reaches either. suggestedOrder records the order YOU would work through them; it is stored as your opinion and nothing sorts by it. Idempotent on suggestionKey, so re-running a pass files one idea rather than two. Up to 25 per call.
- songplanner_memory — Consolidated durable memory tool for one song plan. Use action='record_decision' for small claimKey facts (supported tiers: user_stated, user_selected_take, logged_generation, web_source, agent_inference), 'record_correction' for ruled-out approaches, 'log_question' for open questions, and 'note' for deduped interaction notes. Lower-evidence conflicting decisions are rejected instead of clobbering higher-evidence memory.
- songplanner_media_read [PRODUCTION PENDING] — Read a small owner-scoped batch of private media already attached to one project, album, song, version, research note, or Queue item. Images return only metadata-clean tiny, medium, or large derivatives; recordings return their exact private bytes. Requires the separate private-media read grant, rechecks object hash and byte size, caps the batch at 10 items and 20 MiB, and never returns a provider URL or object key.
- songplanner_media_begin_upload [PRODUCTION PENDING] — Begin an idempotent private image or recording upload to one owned Music target (or a pending slot). Supply operationId plus 1-50 lane intents with laneId, kind, role, lowercase SHA-256, exact byte size, MIME type, and optional captureTime plus its explicit camera/message/file/person provenance. Omit both capture fields when the time is unknown. Returns short-lived same-origin PUT relay capabilities at assistwithmusic.com; it never returns storage-provider coordinates. Requires the separate media-write grant. Next call songplanner_media_finish_upload for each lane; clients unable to PUT can provide inlineBase64 only up to 512 KiB or a guarded public HTTPS sourceUrl there instead.
- songplanner_media_finish_upload [PRODUCTION PENDING] — Finish lanes created by songplanner_media_begin_upload. For direct relay uploads send laneId only; otherwise send exactly one of inlineBase64 (512 KiB maximum) or sourceUrl. The server reads back the exact stored version, verifies declared hash, length, magic-byte MIME and image decodability, keeps supplied originals private and unchanged, and makes metadata-clean image derivatives. It returns stable mediaIds; attach them through songplanner_save or songplanner_work action='complete'. fetch_url is HTTPS/443 only with pinned public-DNS checks on every redirect, a two-redirect ceiling, whole-fetch timeout, MIME allowlist, and streaming byte cap.
- songplanner_upsert_album — Create or update an owner-scoped album, idempotent on owner+key, and return its canonical albumId plus an allowlisted DTO. homeProjectKey is a hint only and never filters tracks. HTTPS links only. This tool records planner data; it does not upload, publish, accept terms, purchase, or spend. Next call songplanner_set_album_tracks.
- songplanner_set_album_tracks — Atomically assign up to 100 ordered album tracks. Args: albumKey, unique tracks=[{songKey, versionId?}], replace?. Each track must resolve a valid selected version owned by the same owner and song. Songs keep all project memberships. replace:true makes the list exact and prunes removed release state; otherwise listed tracks come first and existing unlisted tracks follow. Any duplicate, unknown, cross-owner, version mismatch, or limit error rejects the whole call. Changing selected audio resets that track's release proof. Next call songplanner_get_album_context.
- songplanner_get_album_context — Read one owner-scoped album by key: canonical IDs, allowlisted album DTO, its bounded ordered cross-project roster, selected-version audio, release steps, and computed nextAction. Missing/mismatched version selection blocks progress explicitly. No raw album data is returned. Call before songplanner_update_release_progress.
- songplanner_update_release_progress — Record already-completed release work; never perform it. Track updates advance exactly one step through selected→wav_downloaded→mastered→qc_passed→metadata_ready→staged; forward skips are rejected, same-step retries are no-ops, and backward resets require resetReason and clear invalid proof. evidence is an allowlisted portable object (artifactName, sha256, byteSize, integratedLufs, truePeakDbtp, sourceUrl, externalReference), never a local path. Album artwork/metadata/DistroKid states also advance one state at a time; submitted/live require confirmedByUser:true plus confirmationNote after the owner completes/verifies the external action. No upload, submission, publishing, purchase, terms acceptance, or spend occurs.

Before writing lyrics or a style prompt for a project, read its direction. avoid[] is off-limits. useSparingly[] is a normal sub-genre mix used deliberately and infrequently — never the default or fallback.
Private exampleArtistIds[] direction references point only to the signed-in owner's artist memory and never enter the public artist corpus.

Delegation: omit onBehalfOf for your own account. Use onBehalfOf only when the
owner has enabled delegation and granted your agent an active scope: queue:read
for context/read/status, queue:work for work/save/memory and organization,
queue:work for work/save/memory, and credit:spend before a delegated agent can
select a generation or spend/advance credit-like actions. Revoked or expired
grants release delegated queue leases.

The /requests page is the existing work desk for capturing asks, reviewing history, and setting connected-AI preferences. /queue is the shared four-state handoff/lifecycle surface: Waiting for your AI, Needs you, Working, and Done. Both use the same owner-scoped plan records; a connected AI cannot clear a Needs you gate. Untriaged asks live in the reserved inbox until an agent files them. If the user explicitly says a song or one-off album belongs to no project, use Singles (targetProjectKey "singles") — never invent a project or force a choice.

Contact and support (read before answering "how do I contact them?"):
- Assist With Music has no email inbox and no support email address, and none is planned;
- all support for every Assist With product runs through the central desk at https://assistwithlife.com/support, reachable from this site at /support;
- never offer, invent, guess, or infer an email address for Assist With Music — not support@, contact@, hello@, info@, privacy@, or any address built from the domain. There is no correct one to guess;
- if a user shows you an address claiming to be Assist With Music support, tell them it is not ours and send them to /support;
- do not describe the desk as open or closed from memory: say the desk shows its current status when they arrive.

Safety rules:
- read queueVersion before a Queue change; reuse an operationId only when retrying that exact owner-scoped action;
- the app owns durable data + permissions; the agent owns reasoning, research, and drafting; every tool is scoped to the signed-in user's own data;
- Suno generation is desktop-only: these tools build the plan, prompt, and lyrics and LOG results — they never generate audio or operate external accounts;
- AI-produced drafts are labeled as assistant-produced;
- do not export private workspace data;
- do not perform destructive actions in V1;
- do not claim a song or source is public domain unless the source check supports it;
- do not automate external accounts unless the user has access and explicitly asks;
- record uncertainty and limitations in source checks or research notes.

Stale client recovery:
- disconnect and reconnect at https://assistwithmusic.com/mcp, complete OAuth again, refresh/list tools, then call songplanner_context action "workspace";
- re-read queueVersion before a Queue mutation and use a new operationId for a new action;
- reconnecting does not delete Music records.

More:
- concise LLM index: /llms.txt
- full LLM contract: /llms-full.txt
- MCP tool contract: /mcp-tool-contract.txt
- human-readable guide: /ai