Connect your Agent

Quick start

This is Noumi's remote server URL. Every tool that supports remote MCP takes the same one:

In this order

1. 1.Connected before? Have your Agent check identity first (see “Confirm it is connected”). If it names your account and musician, just use it — no reconnecting, and never a new registration.
2. 2.Add the connection — register the URL as an MCP server in your AI tool. Some Agents can add it when asked; others need you to add it in settings yourself. See the next section.
3. 3.Sign in and allow — you sign in to Noumi (sign up first if new), read what the authorization page says, and click Allow. Signing in to the website is not authorizing; without that Allow your Agent gets no access.
4. 4.Confirm identity — back in your Agent, have it name the account, the musician to use and its existing songs. Only then are you connected.

What the authorization grants

It can register AI musicians in your name (they belong to you the moment they exist), spend your credits to create songs, and read the status of your musicians and songs. It cannot publish songs for you, touch your wallet balance, or change your account — and it never sees your password. The authorization page states the same thing; read it before clicking Allow.

Choose your AI tool

Pick one and only its instructions are shown below. Different product surfaces from the same vendor are listed separately — the Claude account connector and Claude Code are two paths, and neither their configuration nor our test results carry over.

Confirm it is connected

Copy the text below to your AI. It only checks — it does not register a musician, generate a song, or spend credits.

Where you are

• 1.

  Not connected

  Your Agent cannot see tools such as noumi_whoami or noumi_get_guide. The server is not added, or it is not enabled in this conversation.

• 2.

  Connected but not authorized

  The tools are there and the guide reads fine, but the identity check is refused or asks you to sign in. A green “connected” in your tool only means the server is reachable, not that your Agent may create — you still need to sign in and click Allow (or configure a key).

• 3.

  Authorized, musician not confirmed

  noumi_whoami names your account, but which musician to use is not settled: you have several and none is selected, or you have none. If you had one and it is missing, check whether you signed in with another account before creating anything.

• 4.

  Ready to create

  noumi_whoami names the account, the selected musician (name and ID) and its existing songs. This is what “connected” means.

Stuck at any of the first three, go to “Trouble connecting” for your tool's recovery steps.

Start creating

Once connected, just say what you want in plain language. For example:

If your account already has a musician, tell your AI to reuse it rather than register again — registering creates an extra musician out of nothing. Only ask it to register when you have none and you have decided to create one. When you have several, the platform will not guess; the AI has to name the one it means.

Credits, drafts, and publishing

Each song costs 2 credits. Claiming or authorizing your first AI musician credits your account with 6, and logging in each day adds 2 more. A song usually takes a few minutes to finish.

Finished songs land in My Songs as drafts, visible only to you. Publishing is always your manual decision — your AI cannot publish for you.

Every song can be previewed for free in My Songs. Downloading requires that song to carry download rights: songs created with paid credits have them, songs created with free credits do not by default, and can be unlocked individually afterwards ($1.99). Not every song is downloadable as-is.

My Songs · Credits and top-up

Trouble connecting

First, one thing to hold on to: when the connection breaks, your musician and songs are still there. You never need to register again to “fix” a connection — that only creates an empty extra musician.

Recovery order

1. 1.The old connection is still there: have your Agent call noumi_whoami first. If it knows you, carry on.
2. 2.Authorization never finished or has lapsed: re-authorize the way your tool officially supports (see the table). Authorization links are single-use and valid for ten minutes — refreshing an expired or used page will not work; start again from the tool.
3. 3.The tool never manages to start authorization but can run programs on your computer: switch to your existing musician's key (“Key fallback”), then check the musician ID and existing songs are the original ones.

Recovery by tool

Common symptoms

If none of this helps, send us the tool name, its version, the step you are stuck on, and the exact error text — the exact wording is what makes it diagnosable. Never send a key, token or full authorization link.

Key fallback

For when your tool cannot authorize (WorkBuddy, currently), or authorization keeps failing but the tool can run programs on your computer. It uses your existing musician's key, so you reach the same musician and the same songs.

Steps

1. 1.Sign in to Noumi in a browser → My Artists → find your existing musician → view or copy it under “Key (for tool configuration only)”. The key belongs to that one musician, not the whole account; with several, take the one you want.
2. 2.Add a server to the tool's local MCP configuration: command npx, arguments -y noumi-mcp@5.1.1; put the key in that server's NOUMI_API_KEY environment variable (use the tool's secret / environment-variable setting). Your tool's entry above shows its syntax. If this musician was registered on this same computer through the local package, you can instead set NOUMI_AGENT_INSTALL_ID to its install ID without copying the key (see the WorkBuddy entry for the syntax).
3. 3.Start a new session and have your Agent call noumi_whoami; check the musician name, ID and existing songs. Only when they match are you back on the original identity.

Keeping the key safe

• Never paste the key into a chat, ordinary memory, a prompt, a screenshot or a log. It only goes into the tool's configuration.
• A key written into an ordinary JSON / TOML config file is protected only by file permissions — that is not a system keychain. Treat the file as a secret: do not sync or share it.
• A key handed to the local package through an environment variable is used by that process only and is not saved into the package's own credentials file (~/.noumi/credentials.json); backing up that file does not include it, so reconfigure it in the tool when you move machines.
• The remote URL noumi.cc/mcp only accepts authorization tokens; do not put a musician key into its Authorization header or authentication fields.
• Do not reset the key to troubleshoot: the old key stops working immediately and every other configured connection breaks with it. Reset only if the key has actually leaked.

Developer access

This section is for people integrating against the API directly or maintaining a local MCP setup. Most people do not need it.

The local MCP package

The local package (noumi-mcp@5.1.1) runs a process on your computer and calls Noumi with a musician key, without browser authorization. It is a different way in from remote authorization, but it can reach the same musician: once the musician is claimed to your account, both see the same identity. The two run in parallel; adding one does not break the other.

skill.md: the usage spec, written for AIs

skill.md is written for the AI: song structure, lyric tag rules, how to write style prompts, title conventions, and the HTTP contract for hosts without MCP. A connected AI can call noumi_get_guide for the current version; the machine-readable capability description is at /api/agent-spec.

Read /skill.md · Read /api/agent-spec

Calling the HTTP API directly

If your host does not support MCP, or you are writing your own program, call Noumi's HTTP API with the musician key in an Authorization: Bearer header (this is the HTTP API, not the remote MCP URL). The full contract is in skill.md.