Concepts

MCP

You can connect an AI assistant to the API through our MCP server, using your API key.

Connecting

To connect, add https://platform-mcp.nomono.co/mcp to your MCP client with your API key in an Authorization: Bearer header. The server uses stateless streamable HTTP and responds with JSON, and a tool can be called without initialize first.

Requests need Content-Type: application/json and an Accept header that includes application/json, or the server returns 406. Protocol versions 2025-11-25 and 2026-07-28 both work.

To list the tools from a terminal, run the MCP Inspector, which needs Node 22.19 or later:

Shell

npx -y @modelcontextprotocol/inspector@2.9.0 --cli https://platform-mcp.nomono.co/mcp \  --transport http --header "Authorization: Bearer $NOMONO_API_KEY" \  --method tools/list --format json

A tool call is a JSON-RPC request:

curl -X POST "https://platform-mcp.nomono.co/mcp" \  -H "Authorization: Bearer $NOMONO_API_KEY" \  -H "Content-Type: application/json" \  -H "Accept: application/json, text/event-stream" \  -H "MCP-Protocol-Version: 2025-11-25" \  -d '{    "jsonrpc": "2.0",    "id": 1,    "method": "tools/call",    "params": {"name": "list_presets", "arguments": {}}  }'

The tool's result comes back in result.structuredContent, which here is the same body that GET /v1/presets returns.

Authentication

A missing or invalid API key returns HTTP 401 with the same error body as the API. Each tool needs the scope of the route it calls.

Tools

To process a recording, upload each file by calling create_upload, running the part commands it returns and then calling complete_upload. Then call enhance for the tracks and a stereo mix, or create_session and create_job for anything else. Call get_job every few seconds until the job is done, failed or cancelled, and when it's done, list_outputs gives you the download URLs.

Tool	Arguments	What it does	Route and scope
`create_upload`	`pathsize_bytes`	Starts an upload of a local file and returns a shell command per part that uploads it and prints its ETag.	`POST /v1/uploads`jobs:write
`complete_upload`	`upload_idparts`	Completes the upload with each part's number and ETag, and returns the source.	`POST /v1/uploads/{upload_id}/complete`jobs:write
`create_session`	`sourcesretention_days`	Creates a session from sources with their roles, labels and arrays.	`POST /v1/sessions`jobs:write
`create_job`	`session_idproductsoutputsidempotency_key`	Creates a job, sending `idempotency_key` as the `Idempotency-Key` header.	`POST /v1/jobs`jobs:write
`get_job`	`job_id`	Returns the job.	`GET /v1/jobs/{job_id}`outputs:read
`list_outputs`	`job_id`	Returns a done job's files with new download URLs, and its analysis.	`GET /v1/jobs/{job_id}/outputs`outputs:read
`list_presets`	—	Returns the enhancement presets and the position modes.	`GET /v1/presets`Any valid key
`enhance`	`source_idspreset`	Creates a session of microphones and a job for their tracks and a stereo mix.	`POST /v1/sessions, then POST /v1/jobs`jobs:write

The arguments and results have the same shapes as in the API. Deleting things, reissuing part URLs, reading sessions and sources, listing jobs and reading usage are only available in the API.

Uploading

create_upload takes the file's absolute path and size, and each part in its response has a command that uploads that part with curl and prints its ETag. The command for part 2 looks like this:

Shell

tail -c +67108865 /Users/ana/recordings/host.wav | head -c 67108864 | curl -sS --fail -T - -H 'Content-Length: 67108864' -H 'Transfer-Encoding:' -D - -o /dev/null 'https://...' | tr -d '\r' | grep -i '^etag:'

The commands need a POSIX shell with tail, head, curl, tr and grep, and a client without one can only process sources that were uploaded through the API. A command that fails can be run again. Once every part is sent, call complete_upload with each part's number and ETag.

Enhancing in one call

enhance takes one to four sources, which it treats as microphones, and one of the listening presets. If the job can't be created, the error gives you the session ID to retry with create_job. For a recording with a bed or a mixdown, use create_session and create_job instead.

Errors

When the API returns an error, the result has isError: true and one text item:

Error executing tool <tool>: <message>. <hint>. Details: <details as JSON>

For example: Error executing tool create_session: A session has at most four microphones. Details: {"source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90"}

Arguments that don't match a tool's schema return the MCP library's own validation error.

Guidance for assistants

The server sends these instructions on initialize:

Each job is billed for the full length of its session, so know what the user wants back before creating one. If they ask for spatial audio without naming the output, ask one question: a binaural mix (stereo for headphones) or an ADM master (for Dolby Atmos or EBU workflows)? Don't choose for them. Only if they want both, tell them it takes two jobs, each billed in full, and get their agreement first. Describe your plan in terms of what the user gets back, not the API's sessions, jobs or parameters, unless they ask. Never create more jobs than the user asked for, and never retry a failed job without asking.

If your client doesn't pass server instructions on to the assistant, add them to your own instructions.