API reference

MCP

2 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

GET/v1/mcp/rpc

Open the MCP event stream

Free and paid accounts

API key required
Free and paid accounts
No token cost

Opens the Server-Sent Events channel of the MCP transport. Send Accept: text/event-stream and your API key. The answer is 200 with Content-Type: text/event-stream and stays open; the server does not send events on it today, because every request is answered on its own. Most clients do not need it: use POST /v1/mcp/rpc. Without text/event-stream in Accept the answer is 406.

Cost. Free of charge.

curl "https://api.scarleta.ai/v1/mcp/rpc" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Accept: text/event-stream" \
  -i \
  --max-time 5

Parameters

Name	Type	Required	Description
Acceptheader	string	Required	Must list `text/event-stream`.

Errors

Status	Code	Description
429	rate_limit_exceeded	Too many requests from your IP address in the hour. Wait for the `Retry-After` header, then retry.

Example responses

(empty body)

200 The stream is open (`Content-Type: text/event-stream`). The response has no body to read; it ends when you close it.
401 The Authorization header is missing, not a Bearer key, or the key is unknown or revoked. A challenge header `WWW-Authenticate: Bearer` is sent. No tool runs and nothing is charged.
406 The `Accept` header does not list `text/event-stream`.
429 Too many requests from your IP address in the hour. Wait for the `Retry-After` header, then retry.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: rate_limit_unavailable.

POST/v1/mcp/rpc

Send an MCP request

Free and paid accountsUses tokens

API key required
Free and paid accounts
Uses tokens

The Model Context Protocol endpoint for AI clients. Send one JSON-RPC 2.0 message per request: initialize, then tools/list to see the tools and tools/call to run one. It is stateless: there are no sessions, so every request stands alone and answers with plain JSON. The request must send Accept: application/json, text/event-stream. Authenticate with your API key as Authorization: Bearer <key> like every other route. This endpoint is switched on in production. The tools are listed on the MCP tools page; a long-running tool answers with a job_id that you read with the get_analysis_result tool. Protocol failures are JSON-RPC errors, often with HTTP 200. Failures before the protocol (sign-in, bad Content-Type, bad Accept, unreadable JSON) are HTTP errors whose body is documented below; they do not use the standard error body. Requests are also limited per IP address: at most 300 per hour, then 429 rate_limit_exceeded. A notification (a message with no id) is answered 202 with no body.

Cost. Initializing, listing tools and reading a result are free. Calling an audio tool uses tokens at the same rate as the matching analysis: 1 token is 1 second of audio.

curl -X POST "https://api.scarleta.ai/v1/mcp/rpc" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "example-client",
        "version": "1.0.0"
      }
    }
  }'

Parameters

Name	Type	Required	Description
Acceptheader	string	Required	Must list both `application/json` and `text/event-stream`, for example `application/json, text/event-stream`.

Request body

Name	Type	Required	Description
jsonrpcbody	"2.0"	Required
idbody	string \| number	Optional	Request id echoed in the answer. Leave it out to send a notification, which gets no answer body.
methodbody	string	Required	The method: `initialize`, `tools/list`, `tools/call`, `resources/list` or `notifications/initialized`.
paramsbody	object	Optional	Method parameters. `tools/call` takes `{ name, arguments }`.

Response fields

Field	Type	Description
jsonrpc	"2.0"
id	string \| number \| null	The `id` of the request this answers; null when the request could not be read.
result	object	The result of the method, present when the call succeeded.
error	object	Present when the call failed at the protocol level.
error.code	integer	A JSON-RPC error code, for example `-32601` for an unknown method. Allowed: -9007199254740991 to 9007199254740991.
error.message	string
error.data	any

Errors

Status	Code	Description
429	rate_limit_exceeded	Too many requests from your IP address in the hour. Wait for the `Retry-After` header, then retry.

Example responses

{
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {},
      "resources": {}
    },
    "serverInfo": {
      "name": "Scarleta Audio MCP",
      "version": "1.0.0"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

200 A JSON-RPC answer: `result` on success, `error` for a protocol failure such as an unknown method. A `tools/call` that fails inside the tool answers a `result` with `isError: true`.
202 A notification was accepted. The body is empty.
400 The body is not valid JSON.
401 The Authorization header is missing, not a Bearer key, or the key is unknown or revoked. A challenge header `WWW-Authenticate: Bearer` is sent. No tool runs and nothing is charged.
406 The `Accept` header does not list both `application/json` and `text/event-stream`.
415 The `Content-Type` is not `application/json`.
429 Too many requests from your IP address in the hour. Wait for the `Retry-After` header, then retry.

Try it

Other error codes this operation can return: rate_limit_unavailable.