CLI · REST · remote MCP

Connect once.
Resume the same edit.

Give your agent a practical path from an authorized MP3 to a preview and finished song. The resumable CLI keeps work identifiers between steps, asks for explicit spending authorization and stops for your preview decision.

Copy the workflow Hear the real demo

Check your host’s capabilities first.

A host that can do the work

The CLI path needs Python, shell execution and access to your local files. Codex and Claude Code can use this path when those capabilities are enabled. A plain chat window or OAuth-only connector is not enough.

A separately authorized wallet

Signup-free funding requires an x402-capable client and USDC on Base. Confirm the $1.99 / 40-credit pack and any wallet fees. An API key is not a wallet, and installing a connector does not authorize spending.

Private credentials and state

Use LYRICPATCH_API_KEY from your host’s secret store, or a recovered paid --session-state file. Keep the session and run files outside shared folders, repositories and public logs. Never paste keys into a chat.

Files in, playable files out

Give the host an authorized MP3 and UTF-8 text files containing the exact original and replacement words. The host must be able to upload bytes and return or open a local preview—not just print a temporary URL.

These are capability-based setup paths, not claims of an installed marketplace app, universal assistant compatibility or a completed live test in every host. Review your host’s permissions and privacy controls before sharing media.

Resumable workflow · known timestamps

Quote → generate → listen → export

The commands below use the Outlet example’s known 44–48-second selection. Replace the input files and timing for your own song. The 9-credit ceiling covers the total run: one 4-credit generation and one 5-credit export. Funding the balance is a separate purchase.

1. Install the pinned connector

Install LyricPatch 1.2.0 · terminal

python -m pip install 'git+https://github.com/yaboijbigs/[email protected]'

Use Python 3.11+ in a terminal or a shell-enabled agent, not an ordinary chat message. The host integration guide and portable, Codex and Claude plugin files provide the source-controlled setup recipes. They package workflow instructions, not a wallet or media player. No wallet is connected or charged by installation.

2. Connect a funded private identity

Already have an account key? Provide it privately as LYRICPATCH_API_KEY and skip the wallet commands. Otherwise use the signup-free session flow: save the session before the first request, inspect the offer, obtain actual legal and payment permissions, and have your x402 wallet sign the exact challenge. No manual LyricPatch website signup is required.

Before any command, create an owner-only directory outside source control and shared folders. Replace ./private throughout these examples with that directory. On macOS/Linux it must have owner-only permissions; Windows state is protected for the current user and should not be treated as a portable backup.

Optional wallet adapter · install without spending

python -m pip install 'lyricpatch-agent[x402] @ git+https://github.com/yaboijbigs/[email protected]'

Inspect offer or recover · no payment authorization

lyricpatch-agent connect --session-state ./private/session.bin

The CLI wallet adapter uses EVM_PRIVATE_KEY from the local process environment. A trusted operator must provision a dedicated, limited-funds wallet through private host settings, with sufficient USDC on Base and any required fees. Never ask someone to paste a wallet secret into chat or shell history. If your host cannot keep that secret safely, use an existing account key or your own secure x402 signer instead.

Only after the person approves the purchase, confirms they are 18+, accepts the current terms, confirms recording/lyric/voice rights and authorizes media processing, replace CURRENT_FROM_OFFER with the returned legal version and run the funding command. Do not assume these attestations from the example.

Fund $1.99 / 40 credits · only with actual authorization

lyricpatch-agent connect --session-state ./private/session.bin --authorize-1-99-usdc --adult --accept-terms --rights-confirmed --allow-media-processing --legal-version CURRENT_FROM_OFFER

For a funded saved session, append --session-state ./private/session.bin to every preview and export command below. Keep that session file separate from the run file. Pending payment is not a fresh purchase: recover the same session. Never paste session secrets, API keys or state-file contents into a prompt. Lost signup-free secrets have no email recovery.

3. Prepare and quote without generating

Place your authorized MP3 at song.mp3, and put the exact approved lyrics in original.txt and replacement.txt. Choose a private directory for the state files. Use --rights-confirmed only after rights and media-processing permission are actually confirmed. This step uploads and prepares audio; it does not generate a lyric change.

Prepare & quote · no generation authorization

lyricpatch-agent preview --song song.mp3 --original-file original.txt --replacement-file replacement.txt --start 44 --end 48 --max-credits 9 --state ./private/outlet-run.bin --output preview.wav --rights-confirmed

Want a finished WAV instead? Set --format wav on this first preview command and keep it on preview retries. The export format is part of the saved intent; do not add that flag later to the export command. Choose a matching finished.wav output path for export.

4. Approve generation, then play the preview

Read the quote and get approval. Only then use the authorized form below, keeping the same run state. On completion, ask your host to play or attach preview.wav, or open it in your local audio player. Do not treat a successful command as the owner liking the result.

Generate · only after quote approval

lyricpatch-agent preview --song song.mp3 --original-file original.txt --replacement-file replacement.txt --start 44 --end 48 --max-credits 9 --state ./private/outlet-run.bin --output preview.wav --rights-confirmed --authorize-generation

If work is still running or the connection drops, rerun the same stage with the same state file. Do not delete state or change identifiers to force a retry. Corrected content or an alternate version needs a fresh quote and separate approval; successful alternate generations cost credits again.

5. Approve the version, quote the export

After listening, use --approve-version only for the version the owner chose. This selects it and requests an export quote; it does not authorize the export charge.

Select approved version & quote export

lyricpatch-agent export --state ./private/outlet-run.bin --output finished.mp3 --approve-version

Approve the separate 5-credit export before adding --authorize-export. The command writes the finished song to finished.mp3. Have your host attach that file or show its local path; download before the project’s 24-hour expiry.

Export · only after version and cost approval

lyricpatch-agent export --state ./private/outlet-run.bin --output finished.mp3 --approve-version --authorize-export

For remote MCP hosts

Discover publicly.
Work privately.

An MCP host needs Streamable HTTP and custom bearer headers for private work. Anonymous initialization, tool listing and get_service_info expose public service information only. Fund over REST, then configure the returned API key privately. The host still needs file transfer, playback and a separately authorized wallet path.

Verified published MCP Registry record · REST, phrase matching and recovery

Remote MCP · secure host configuration

Transport: Streamable HTTP
Server URL: https://api.lyricpatch.com/mcp
Authorization: Bearer <api_key from your funded session, or account agent key>

Public MCP metadata discovery: initialize, tools/list and get_service_info.
Fund a signup-free session over REST before using private MCP tools.
Capable hosts can bootstrap and connect the returned key automatically.
Store the key in your client's secret manager.
Never include a real key in a public configuration file.

Also discoverable in the live Glama connector listing, verified September 14, 2026. Directory discovery does not install the connector, grant private access or authorize payment.