Sonilo Setup
Guide the user through connecting to Sonilo. There are several ways in — pick based on what the user is actually doing, not just whichever is listed first:
| Path | Needs an API key? | Best for |
|---|
| A. (CLI sign-in, credential shared with the local MCP server) | No — OAuth in the browser | Anyone on a machine with a browser. One sign-in covers the CLI and , so the MCP config carries no secret. |
| B. Remote OAuth MCP plugin () | No — OAuth sign-in | Claude Code users who want nothing running locally. Full tool coverage. |
| C. API key () | Yes | CI, containers, headless boxes, and anyone who prefers holding a key. Works with every client. |
Choosing:
- On a machine with a browser and any MCP host → Path A. It is the shortest path and leaves no secret in a config file.
- Claude Code specifically, and nothing local wanted → Path B.
- No browser (CI, a container, a remote box), or the user says they already have a key → Path C.
- Not working through an agent at all (writing code, scripting a shell) → Path D at the end; the MCP configuration in A–C does not apply.
Step 0: Check what already works (all paths)
Do this before changing anything — the answer is often "nothing to do".
There are two transports, and either one is enough. Probe both before
concluding that nothing is set up.
- MCP: is a MCP server connected (any Sonilo tool, e.g. or , available to call)? If so, call the free, read-only .
- CLI: if there are no Sonilo tools, run — the same free, read-only call as above. Exit code 0 means the CLI is installed, signed in, and reaching the API, and the skills can drive it directly. Do not probe with : it exits 0 even when signed out, so it cannot separate the two states, and on an account with no display name it prints an empty line that reads like a broken credential. It is worth running only to show which account is active, never to decide.
- Either one succeeds: Sonilo is configured and working. Say so and stop. Ask only whether they want to rotate credentials.
- Fails with 401: authentication is stale, not missing. If they signed in with , the key may have expired (90 days) or been revoked — again fixes it. Otherwise the key is wrong: continue at Path C.
- Neither responds: nothing is connected — pick a path below and run it. MCP is the better default (it needs no shell, and it is the only transport that survives a dubbing job's two-hour poll), but a CLI that is installed and signed in is a complete setup on its own; do not make someone configure MCP they will not use.
Never print, quote, or echo a key or the contents of the credential file. If you must refer to one, redact it.
Path A: (no API key, any MCP host)
One sign-in, then both the CLI and the local MCP server are authenticated — the
CLI writes a credential to
~/.config/sonilo/credentials.json
and
(0.16.0 and later) reads it.
bash
npm install -g sonilo-cli # or: pip install sonilo-cli
sonilo login
The CLI prints a one-time code and opens the browser to
platform.sonilo.com. The user signs in to their
Sonilo Platform account
(separate from a consumer sonilo.com account), confirms the code matches what
the terminal printed, and approves. On a machine without a browser, add
and have them approve the printed URL from another device.
Then add the MCP server with no secret in the config:
bash
claude mcp add sonilo -- uvx sonilo-mcp # Claude Code
codex mcp add sonilo -- uvx sonilo-mcp # Codex
For Claude Desktop, the whole config is:
json
{
"mcpServers": {
"sonilo": { "command": "uvx", "args": ["sonilo-mcp"], "env": {} }
}
}
Both need the
package manager (provides
): install it with
(macOS),
/
, or
winget install --id=astral-sh.uv
(Windows) — other methods at
https://docs.astral.sh/uv/getting-started/installation/.
Worth telling the user up front:
- Approving mints an ordinary API key on their account, named , that expires after 90 days and is visible and revocable at https://platform.sonilo.com/dashboard/api-keys.
- shows which account and source is active; revokes the key server-side and then forgets it locally.
- An exported takes precedence over the sign-in. If tools authenticate as an unexpected account, check for that variable first — says so explicitly when it is set.
- Sign-in is for humans. Provisioned/POC accounts are issued a key by Sonilo and cannot use ; those users belong on Path C.
Validate with
, exactly as in Step 0.
Path B: Remote OAuth plugin (Claude Code only, no API key)
claude
/plugin marketplace add sonilo-ai/sonilo-claude-plugin
/plugin install sonilo@sonilo
The first Sonilo tool call opens the browser to sign in to a
Sonilo Platform account (platform.sonilo.com — separate from a consumer sonilo.com account) and approve access. Claude Code stores the resulting token per-user in the OS keychain; nothing to copy, paste, or configure. Review or disconnect anytime from
.
This connects to a single hosted endpoint (
https://api.sonilo.com/mcp
, OAuth 2.1 + PKCE) that carries the same tool set as the local server (Paths A and C): music/SFX from text or video, video-to-video music/SFX, video-to-sound, video-to-video-sound, dubbing, audio ducking, and account/usage. Paths A and C are still the better fit for MCP hosts other than Claude Code, or for users who prefer holding and managing their own key.
Path C: API key (CI, containers, or by preference)
Step 1: Get an API key
Only take this path when Path A does not fit — no browser, a provisioned
account, CI, or an explicit preference for holding a key. Tell the user:
(Need an account? Sign up there first — self-serve accounts start with a few free generation runs on most endpoints, no card required.)
Once you have a key (it looks like
), tell me and I'll connect it — don't paste it directly into this chat if you can avoid it; I'll wire it into the MCP server config instead.
Step 2: Connect the MCP server
Once the user has a key, connect the
MCP server with it. Prefer the CLI form when the host supports it:
bash
claude mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp
For hosts without that CLI (Claude Desktop, Codex), edit the MCP config directly:
Claude Desktop (
claude_desktop_config.json
):
json
{
"mcpServers": {
"sonilo": {
"command": "uvx",
"args": ["sonilo-mcp"],
"env": { "SONILO_API_KEY": "sk-..." }
}
}
}
toml
[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]
[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."
Both require the
package manager (provides
) — if not already installed, use
,
/
, or
winget install --id=astral-sh.uv
(see
https://docs.astral.sh/uv/getting-started/installation/ for other methods). After editing a config file directly, tell the user to restart the host app (Claude Desktop/Codex) — a
in Claude Code takes effect on the next session without a restart.
Step 3: Validate
- Succeeds: confirm Sonilo is configured and working. Mention also shows what free-trial runs remain per service.
- Fails (401): the credential is wrong. On this path that means a bad key — point back to the dashboard link in Step 1 and ask for a corrected one. If the user signed in with instead, the key behind that sign-in has expired or been revoked: again.
- No Sonilo tools appear at all: the MCP server itself isn't connected — re-check Step 2's config location and confirm the host was restarted/reloaded.
Path D: Python/JS SDK or CLI (no MCP)
Not every integration goes through an MCP host. If the user is writing code or scripting from a shell:
bash
pip install sonilo # Python SDK
npm install sonilo # JS/TS SDK
pip install sonilo-cli # Python-distributed CLI
npm install -g sonilo-cli # npm-distributed CLI
Same API key as Path C — get one from
https://platform.sonilo.com/dashboard/api-keys and set it as
in the environment (both SDKs and both CLIs read it automatically; no MCP config,
, or plugin install involved). Validate with the SDK's own account call (
client.account.services()
/
sonilo.account.services()
) or
on the CLI.
Optional Configuration (local MCP server)
Mention these only if relevant to what the user is trying to do — they all have sane defaults:
| Variable | Default | When to mention it |
|---|
| | Only for a non-default deployment. |
| | Where generated files are saved by default, and the base for relative input paths. Suggest changing it if the user wants output elsewhere. |
SONILO_MCP_ALLOW_ANY_PATH
| | Set only if the user needs to read/write files outside — explain this widens the tool's file-system access before suggesting it. |
| | Raise this if the user hits generation timeouts on long videos — note that / (see task-recovery) can always recover a timed-out result regardless of this setting. |
Safety Rules
- Never ask the user to paste an API key, token, or secret directly into chat if a config-file or path is available.
- Never print or echo the key's value once configured.
- Point users at the dashboard (https://platform.sonilo.com/dashboard/api-keys) to create or rotate keys, and at https://platform.sonilo.com/dashboard/billing for billing/top-up — never fabricate either URL's content.