MasterForge API

MasterForge runs as an MCP server, so an agent can discover the tools and use them without you writing an integration. It is the same pipeline the website runs, metered in the same credits, with the same results in your account afterwards.

Getting started

1. Create a key

   Open your account page and find the API keys card. Name the key after the machine or agent that will hold it. Choose Full access if it should be able to start runs, or Read only for a key you are pasting into a shared config.

   The key is shown once, at the moment you create it. Only a fingerprint is stored, so nobody can display it again later, including us. If you lose one, revoke it and make another. Creating keys is free.

2. Point your client at the server

   Streamable HTTP, stateless JSON. The key travels as a bearer token.

   {
     "mcpServers": {
       "masterforge": {
         "type": "http",
         "url": "https://lmeiidgiljujxkpqwbxq.supabase.co/functions/v1/mcp",
         "headers": {
           "Authorization": "Bearer mf_live_YOUR_KEY_HERE"
         }
       }
     }
   }

3. Ask for what you want

   The tools describe themselves, so an agent works out the sequence on its own. In practice you say something like "restore this track and tell me what changed" and it handles the upload, the run and the download link.

The tools

A full run, start to finish

This is an Auto-Master, the longest path. Analysis and Preparation are the same shape with one fewer stage and a lower price.

1. Reserve an upload

   masterforge_create_upload({
     filename: "my track.wav",
     size_bytes: 51840044,
     content_type: "audio/wav",
     idempotency_key: "my-track-take-1"
   })

   You get back an upload_id and a URL. Send the file to that URL with an HTTP PUT. The audio goes straight to storage and never passes through the API, so file size is not a protocol problem. The URL is valid for 15 minutes.

2. Start the run

   masterforge_master_track({ upload_id: "pan_a1b2c3d4e5f6" })

   This returns immediately with a run_id and the credits charged. It does not wait for the work, because a full master takes minutes and a blocked call would be retried by most clients, which is how you end up paying twice for one master.

3. Poll until it is done

   masterforge_get_run({ run_id: "pan_a1b2c3d4e5f6" })

   Call it every 20 to 30 seconds. The reply carries state, the current stage, and a next line telling you what to do. A full Auto-Master typically takes around five minutes end to end.

4. Collect the result

   masterforge_get_result_url({
     run_id: "pan_a1b2c3d4e5f6",
     artifact: "master"
   })

   You get a download link rather than the file itself, deliberately: a 50 MB WAV inside a tool response would fill an agent's context window and be paid for in tokens on every later turn. The link expires, and this tool is free to call again for a fresh one, so coming back tomorrow costs nothing and re-runs nothing. You also get the usual email when a run finishes.

Limits

Limits are counted per key, not per account. That way a script that gets stuck in a loop can be revoked on its own without locking you out of the website.

Going over a limit returns rate_limited with a retry_after_seconds value. Errors in general are written to be acted on: running out of credits tells you the shortfall, where to top up, and which cheaper tool still fits your balance.

Files and privacy

Audio you send through the API is handled exactly as audio you upload on the site: it is stored in the EU, processed on our own server in Helsinki, and used only for your run. Audio is deleted automatically 90 days after a run finishes. The analysis, the mastering plan and your run history are kept, so you can still see what was measured and decided. After that, masterforge_get_result_url answers with a clear message rather than a broken link.

Full detail is in the privacy policy.

Not in this version

• Fetching audio from a URL. Uploading works, and a server that fetches arbitrary URLs on request is a security hole worth avoiding for a convenience. Revisit if a caller with no local filesystem turns up.
• Webhooks. Polling needs nothing running on your side. Callbacks would.
• Batch. One track per run. A batch is a loop with a rate limit around it, which is what the limits above are.
• The free browser tools. They run on your machine, so there is nothing for a server to serve.