SunoMCP

suno_manage_project

Create, retrieve, save, and render Suno music projects; upload audio, add or generate tracks, replace sections, commit candidates, and remove tracks using version IDs.

Instructions

Create, retrieve, save, upload, add/generate/replace tracks, commit, remove, or render a project.

Use the latest version_id for mutations. Seconds describe the source audio;
beats describe the project timeline. Generation only creates candidates;
commit_candidate explicitly adds one to the selected track. Preserve returned
project/version/operation/candidate IDs. Poll accepted task_id with suno_get_task
until finished_at is set, then inspect response.success. On timeout, retry the
SAME request/key or poll its original task; never automatically regenerate.

Input Schema

Name	Required	Description	Default
`request`	Yes
`idempotency_key`	No	Required for every action except retrieve. Choose a new stable key for each intended write; retry an uncertain submission with the SAME key and identical request. Changing the key can create a second billable operation.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.25Nov 2, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses async task semantics (accepted task_id, finished_at, response.success), the candidate-vs-committed distinction, stale-version conflict detection, and the idempotency/duplicate-billing risk of changing keys. It stops short of stating which actions are destructive (remove_track, replace_section, render) or what permissions are needed, so it is not fully complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The action inventory is front-loaded in the first sentence and the remaining sentences each carry a distinct operational rule (units, candidate/commit, ID preservation, polling, timeout). It is dense but earns its length for a ten-action tool, with only minor redundancy between the version_id rule here and in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers the async polling loop, candidate lifecycle, and retry policy that the schema cannot express. What remains missing is a per-action indication of destructive versus read-only behavior and any mention of prerequisites such as required audio/render IDs before generate_track, which matters for a tool spanning this many mutations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 50% schema coverage the description must compensate, and it adds real meaning: seconds describe source audio while beats describe the project timeline, and version_id must be the latest from retrieve. The nested action-specific fields (model enums, stem_control_tags, render_audio_id) are documented in the schema but not reinforced in the description, leaving partial reliance on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete enumeration of the ten operations this tool performs (create, retrieve, save, upload, add/generate/replace tracks, commit, remove, render), so the agent knows exactly what resource and verb set it covers. However, it never distinguishes itself from siblings that overlap, notably suno_replace_section and suno_add_stem, which an agent could easily confuse with this tool's replace_section and add_track actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Strong workflow guidance: use the latest version_id for mutations, generation only produces candidates while commit_candidate adds one, poll accepted task_id with suno_get_task until finished_at, and on timeout retry the SAME request/key rather than regenerating. The one gap is that it never states when to choose this tool over the similarly-named sibling suno_replace_section, so sibling-level routing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server