Help center · AI agents
Connect your AI agent.
LyricalWriter runs a remote MCP server, so Claude, ChatGPT, Cursor, or any MCP-capable agent can write, organize, release, and play your songs — 117 tools, acting only on your account.
https://lyricalwriter.com/api/mcpSetup
Connect in a minute.
Pick your app. Most connect with a sign-in — add the server URL, sign in to LyricalWriter in the window that opens, and approve the access level. No keys to copy.
- 1
In Claude (web or desktop), open Settings → Connectors and choose Add custom connector.
- 2
Name it “LyricalWriter” and paste the server URL below.
- 3
Sign in to LyricalWriter in the browser window that opens, choose an access level, and approve.
- 4
Say “Check which LyricalWriter account you're connected to.” — your agent should answer with your name and plan.
https://lyricalwriter.com/api/mcpThe server introduces itself when an agent connects — workflows, conventions, and limits — so even an agent that has never heard of LyricalWriter knows where to start. Already connected? Ask your agent for “the LyricalWriter guide” and it will link you back here.
Examples
Just ask in plain words.
“Write a moody synth-pop song about night trains in my “Nova” persona and save it.”
“Tighten the rhymes in the second verse of “Night Drive” — keep the chorus.”
“Brainstorm five breakup-song concepts and keep the two best in my “Next EP” folder.”
“Play the chorus of my latest song on my laptop, then move it to my phone.”
“Make a 30-second music video of the chorus of “Night Drive”.”
“What’s still missing before “Night Drive” can go to DistroKid?”
“Find upbeat indie-pop songs in the community and save the best one to my Liked Songs.”
“Invite my co-producer to edit my “Road Trip” playlist.”
Safety
You stay in control.
Your account only
Agents act as you and can only see your own content plus public community songs. Everything they create is saved as a private draft.
Asks before it matters
Spending music-video credits, entering a challenge, inviting a collaborator, and every delete are two-step: the agent must show you a summary and get your explicit yes. Nothing happens on the first call.
Undo built in
Before an agent edits a song it saves a checkpoint to the song's version history, so any change can be rolled back from the editor's History panel.
Access levels for sign-in connections
API keys always have full access except deletes, which are off until you enable “Allow deletes” on that key.
What the labels in the tool list mean
Limits
Same limits as the app.
- AI generations: 1,000 per day on Pro, 50 on trial — one generation is one AI call. Shared with the app; resets at midnight UTC. Failed generations are refunded.
- Music videos use music-video credits (1 per video; Cinema models use 2). Re-rendering a paid video is free, and a cancelled render that produced no footage gets its credit back.
- Music videos run up to 30 seconds. The final MP4 is stitched and exported in the studio — your agent hands you the link.
- Song alignment (exact section timing and synced lyrics) has its own daily allowance and is cached, so each song only pays once per audio and lyric version.
- Each tool has a per-minute rate limit shared with the matching feature in the app. Trial accounts get half Pro's per-minute rate.
- Agent access requires an active Pro subscription or trial. Account, billing, and a few guides keep working after a plan lapses.
Reference
All 117 tools.
You never call these yourself — your agent picks them. This list is here so you know exactly what an agent can and can't do.
117 tools
Account & setup · 7
Who the agent is acting as, your plan, allowances, and preferences.
- Confirms which account the agent is using, your plan, and today’s AI allowance. Agents call it first.Read
whoami - The Gemini, ChatGPT, and Claude models available for writing, grouped by provider.Read
list_models - Today’s AI generations used and remaining, and when the allowance resets.Read
get_usage - Your plan, whether it’s active, music-video credits available, and today’s AI usage.Read
get_billing_status - Your writing defaults, playback settings, caption style, and notification toggles.Read
get_preferences - Changes any of those preferences — only the ones named. Agents can turn remote playback off, never back on.Write
update_preferences - “What should I work on?” — recent edits, drafts without audio, releases due, unread notifications, and suggested next steps.Read
get_studio_briefing
Writing · 8
Generate and polish lyrics. Nothing is saved until the agent calls save_lyric.
- Writes a complete original song — title, sections, Suno prompt, and style tags — optionally in a persona’s voice.AI
generate_lyrics - Rewrites lyrics to an instruction (tighter rhymes, better flow, new perspective) while keeping section markers.AI
improve_lyrics - Perfect, near, and creative multi-syllable rhymes for a word.AI
suggest_rhymes - Autocompletes the line you’re on, matched to meter and rhyme.AI
suggest_next_line - Five alternative titles drawn from the lyrics.AI
suggest_titles - An optimized Suno style prompt and tag list for a song.AI
generate_suno_prompt - Free syllable counts per line, plus the lines that break the section’s meter.Read
analyze_meter - Rewrites one section so it scans like another, line for line (not saved automatically).AI
match_meter
Ideas · 11
Brainstorm, research, and keep song concepts — organized into folders.
- Song concepts with titles, hook, structure, imagery, point of view, and an opening line.AI
brainstorm_ideas - Develops one saved idea in one direction: chorus, verse, bridge, titles, or a deeper concept.AI
refine_idea - Researches an artist’s lyrical style on the web, then writes original ideas in that lane plus a reusable style brief.AI
research_artist_style - Your saved ideas, newest first — short by default, full detail on request.Read
list_ideas - One idea in full, including every refinement.Read
get_idea - Creates or updates one idea (or files it into folders).Write
save_idea - Saves several new ideas at once — e.g. the keepers from a brainstorm.Write
save_ideas - Your idea folders.Read
list_idea_collections - Creates or renames an idea folder.Write
save_idea_collection - Permanently deletes an idea.Delete
delete_idea - Permanently deletes an idea folder (the ideas inside stay).Delete
delete_idea_collection
Songs & library · 11
Find, read, save, and organize the songs in your library.
- Resolves “that song about the ocean” or “my drafts with audio” to songs — search words plus filters.Read
find_songs - Browses your songs, most recently updated first, with paging.Read
list_lyrics - One song in full: every section plus its metadata.Read
get_lyric - Creates a song or updates one (title, sections, genre, status, tags…). New songs are private drafts.Write
save_lyric - Replaces the text of one section and saves — the old text is checkpointed first.Write
update_lyric_section - Favorites or pins a song (pinned songs sit at the top of your library), or favorites an idea.Write
set_favorite - Copy-ready Suno text: formatted lyrics, style prompt, and tags in one block.Read
get_suno_export - Imports your finished track from an https link (e.g. a Suno song) as the song’s audio.Write
attach_song_audio - Download links for the song’s audio, cover, rendered videos, and a synced-lyrics summary.Read
get_song_assets - Permanently deletes a song with its videos, versions, and comments.Delete
delete_lyric
Version history & comments · 8
Every agent edit is checkpointed first, so you can always roll back.
- A song’s saved versions — the same history as the editor’s History panel.Read
list_lyric_versions - One version in full, with a diff against the current song.Read
get_lyric_version - Saves a named restore point (with an optional note) before a big change.Write
save_lyric_version - Rolls a song back to a saved version (the current text is checkpointed first).Write
restore_lyric_version - Section comments on a song — on your songs and ones you co-write.Read
list_comments - Posts a note on a section, as you.Write
add_comment - Marks a comment resolved, or reopens it.Write
resolve_comment - Deletes a comment (any on your songs; only your own on songs you co-write).Delete
delete_comment
Personas · 5
Artist identities that give generated lyrics a consistent voice.
- Drafts an artist persona from a one-line description.AI
generate_persona - Your artist personas.Read
list_personas - One persona in full — voice, delivery, themes, influences.Read
get_persona - Creates or updates a persona.Write
save_persona - Permanently deletes a persona.Delete
delete_persona
Cover art & captions · 5
Artwork and release-day social copy.
- Generates album art for a song and sets it as the cover.AI
generate_cover_art - Tweaks the existing cover with one instruction.AI
refine_cover_art - Chooses which stored image is the song’s cover (e.g. an earlier generation).Write
set_cover_art
Collections (albums & EPs) · 6
Release containers — albums, EPs, singles, mixtapes. Not playable; playlists are.
- Your albums, EPs, singles, and mixtapes.Read
list_collections - One collection with its track list.Read
get_collection - Creates or updates a collection.Write
save_collection - Adds a song as the next track.Write
add_lyric_to_collection - Removes a track and renumbers the rest.Write
remove_lyric_from_collection - Permanently deletes a collection (the songs stay).Delete
delete_collection
Playlists & collaboration · 14
Playable mixes of your songs and public community songs — shareable and collaborative.
- Your playlists, including ones shared with you as a collaborator.Read
list_playlists - One playlist with its live track list.Read
get_playlist - Creates a playlist (or updates one).Write
upsert_playlist - Renames a playlist or changes its description.Write
update_playlist - Adds songs — yours with audio, or community songs with public audio.Write
add_playlist_tracks - Removes songs and renumbers the rest (owners and collaborators).Write
remove_playlist_tracks - Moves a song to a new position (owners and collaborators).Write
reorder_playlist_tracks - Makes a playlist public (needs at least one song with public audio) or private again.Write
publish_playlist - Who can edit a playlist, and how many invite links are active.Read
list_playlist_collaborators - Creates a 7-day invite link that lets someone add, remove, and reorder songs.Needs your OK
invite_playlist_collaborator - Joins a playlist from an invite link someone sent you.Write
join_playlist - Stops collaborating on someone else’s playlist.Write
leave_playlist - Removes a collaborator and/or turns off outstanding invite links.Delete
remove_playlist_collaborator - Permanently deletes a playlist.Delete
delete_playlist
Listening (LyricalWriter Connect) · 9
Every browser or installed app where you have LyricalWriter open becomes a speaker your agent can drive.
- Your open LyricalWriter tabs and apps, online status, and what each is playing.Read
list_devices - What’s playing now: track, position, volume, shuffle/repeat, queue, section loop.Read
get_playback_state - Plays a song, playlist, Liked Songs, or search — even a specific section like “the second chorus”.Playback
play - Pause, resume, skip, seek, volume, shuffle, repeat, stop, or leave a section loop.Playback
control_playback - Queues songs to play next or at the end.Playback
queue_tracks - Moves what’s playing to another device (laptop → phone) at the same spot.Playback
transfer_playback - Section start/end times in the audio, plus the hook window.Read
get_song_sections - Word-accurate timing alignment (paid, cached per audio and lyric version, 30–90s).AI
align_song - Synced lyrics as an .lrc file — per line for distributors, per word for karaoke.Read
get_synced_lyrics
Lyric videos & music videos · 12
Agents set up and render videos; the final MP4 is exported in the studio, so they hand you the studio link at the end.
- Your lyric-video projects, newest first.Read
list_videos - One lyric video: template, alignment status, renders, share and karaoke links.Read
get_lyric_video - Sets up a word-synced lyric video for a song with an MP3 (alignment only when asked; it uses the alignment allowance).AI
create_lyric_video - Your AI music-video projects, newest first.Read
list_music_videos - One music video: per-shot progress, exports, cost estimate. While rendering, each check collects finished clips.Read
get_music_video - Creates a music-video project and plans its storyboard (one AI generation; no credits spent).AI
create_music_video - Renders the music video — uses your music-video credits, so it always asks first.Needs your OK
generate_music_video - Stops a render; a video that produced no footage gets its credit back.Write
cancel_music_video - Renames a lyric or music video, or turns its public share link on or off.Write
update_video_project - Permanently deletes a lyric or music video (refused while a render is running).Delete
delete_video_project - Step-by-step checklist for making a lyric video in the studio.Read
guide_lyric_video - Step-by-step checklist for making an AI music video in the studio.Read
guide_music_video
Releases · 5
Track every song from finished audio to live on streaming platforms.
- Songs in your release pipeline, with their stage.Read
list_releases - Release readiness for one song: pipeline steps, distributor checklist, and a copy-ready metadata block.Read
get_release - Sets release date, distributor, links, metadata, and submitted/live status.Write
update_release - Popular distributors with links and a one-line highlight.Read
list_distributors - Step-by-step guide to turning lyrics into a finished track on Suno.Read
guide_song_creation
Community · 13
Discover, like, save, and remix public songs; enter the daily challenge.
- Browses public community songs.Read
search_community - Likes or unlikes a song (they appear in your Liked Songs).Write
like_song - Your Liked Songs, with whether each is playable.Read
list_liked_songs - Bookmarks a community song, or removes the bookmark.Write
save_song - Your bookmarked community songs.Read
list_saved_songs - Copies a remixable public song (or your own) into your library as a new private draft, credited to the original.Write
remix_song - Follows or unfollows a creator.Write
follow_artist - Saves someone else’s public playlist to your library, or removes it.Write
save_playlist_to_library - A persona’s artist radio station and its tracks.Read
get_artist_radio - Artists trending in the community right now.Read
list_trending_artists - Likes, views, saves, and remixes across your own songs and playlists.Read
get_song_stats - Today’s daily songwriting challenge and whether you’ve entered.Read
get_current_challenge - Enters one of your songs in today’s challenge — it becomes public, so it always asks first.Needs your OK
submit_challenge_entry
Notifications · 3
Your notification bell.
- Renders finished, achievements, reminders, payment issues, and system messages.Read
list_notifications - Marks specific notifications, or all of them, as read.Write
mark_notifications_read - Deletes specific notifications, or all read ones.Delete
delete_notifications
Shortcuts
Built-in prompts.
Many clients list these in their prompt or slash-command menu — pick one to start a guided workflow. Clients that show interactive cards also get a live Now Playing card with transport controls.
Write a song
write_a_songGuided flow from idea to a saved song, optionally in a persona’s voice.
Finish this song
finish_this_songPicks up an unfinished draft and takes it to done.
Export a song to Suno
export_to_sunoGets a song Suno-ready: formatted lyrics, style prompt, and tags.
Plan a release
plan_releaseBuilds a release plan for a song: date, distributor, assets, captions.
Release check-in
release_checkinReviews what’s still missing before a song can ship.
Studio briefing
morning_briefing“What should I work on today?” from your recent activity.
DJ session
dj_sessionHands-free listening — play, skip, loop choruses, move between devices.
Set up hands-free listening
hands_free_setupWalks you through getting a device ready for agent playback.
Troubleshooting
If something goes sideways.
The agent says “No LyricalWriter device is online.”
Playback goes to a browser tab or installed app where you're signed in to LyricalWriter. Open lyricalwriter.com on the device you want to hear it on, then ask again. Agents can also send a one-tap notification that starts playback when you open the app.
It says the device “needs a tap”.
Browsers block audio until you've interacted with the page once. Tap Play in the LyricalWriter tab on that device (a banner shows there). After that first tap, playback is hands-free.
Section jumps (“play the chorus”) land slightly early or late.
Until a song is aligned, section times are estimates. Ask the agent to align the song (align_song) for word-accurate timing — it uses your alignment allowance and is cached afterwards.
The agent got a TRIAL_EXPIRED error.
Agent access follows your plan. Renew or upgrade in Settings → Billing, then try again — your connection keeps working without reconnecting.
It got INSUFFICIENT_SCOPE.
The connection doesn't have permission for that action. Publishing, inviting collaborators, and deletes need full access: reconnect approving full access, or — for API keys — turn on “Allow deletes” for that key in Settings → API Keys.
It hit RATE_LIMITED.
Each tool has a per-minute limit, and AI generation has a daily cap (1,000 on Pro, 50 on trial). The error tells the agent exactly how long to wait; the daily cap resets at midnight UTC.
My music video still says “generating”.
Renders take a few minutes. Each time the agent checks the video (get_music_video) it collects finished clips. When every shot is ready, open the studio link it gives you to stitch and export the final MP4.
How do I disconnect an agent?
OAuth connections: remove the LyricalWriter connector in your client. API keys: revoke the key in Settings → API Keys — access stops immediately.
Still stuck? We read every message.
Contact support