MCP Server

Give Claude, Cursor, VS Code and other MCP clients AudioLab's models, catalog and docs as tools, with your API key.

Before You Begin

AudioLab runs a hosted Model Context Protocol server at https://api.tryaudiolab.ai/mcp. It speaks Streamable HTTP and authenticates with an API key sent as Authorization: Bearer. There is no OAuth sign-in, so a client must be able to send that header; clients that cannot, such as Claude Desktop, run the small local package shown below.

Create a key for each client in the dashboard (Create and Use a Key). The key's scopes decide which tools the client sees, and a spending limit caps what the paid tools can spend. Export it as AUDIOLAB_API_KEY before running the commands on this page.

Claude Code

claude mcp add --transport http audiolab https://api.tryaudiolab.ai/mcp \
  --header "Authorization: Bearer $AUDIOLAB_API_KEY"

The shell expands the key, so Claude Code stores its value in its configuration. Run claude mcp list to check the connection, then ask for a tool by name, for example "use list_models to find speech models".

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in one project. Cursor reads the key from the environment it starts in.

{
  "mcpServers": {
    "audiolab": {
      "url": "https://api.tryaudiolab.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:AUDIOLAB_API_KEY}" }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json. VS Code asks for the key the first time the server starts and keeps it in its secret storage.

{
  "inputs": [
    { "type": "promptString", "id": "audiolab-key", "description": "AudioLab API key", "password": true }
  ],
  "servers": {
    "audiolab": {
      "type": "http",
      "url": "https://api.tryaudiolab.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:audiolab-key}" }
    }
  }
}

Claude Desktop

Claude Desktop's custom connectors sign in with OAuth, so connect through the local package instead. It needs Node.js 20 or later. Open Settings, then Developer, then Edit Config, add the server and restart Claude Desktop.

{
  "mcpServers": {
    "audiolab": {
      "command": "npx",
      "args": ["-y", "https://tryaudiolab.ai/cli/mcp-0.1.0.tgz"],
      "env": { "AUDIOLAB_API_KEY": "YOUR_AUDIOLAB_API_KEY" }
    }
  }
}

The file holds the key in plain text. The package forwards every call to the hosted server, so its tools, costs and errors are the same.

Other Clients

A client with remote server support needs the URL https://api.tryaudiolab.ai/mcp, the Streamable HTTP transport and the Authorization header. The server is stateless: it issues no session ID, and a GET for a server event stream answers 405. A client that only starts local servers runs npx -y https://tryaudiolab.ai/cli/mcp-0.1.0.tgz with AUDIOLAB_API_KEY in its environment.

To check a key without a client, call a free tool directly. The answer arrives as one server-sent event.

curl --fail-with-body --show-error --silent "$AUDIOLAB_API_URL/mcp" \
  -H "Authorization: Bearer $AUDIOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_key_info", "arguments": {}}}'

Tools

Tool	What It Does	Key Scope	Cost
`list_models`	Searches the catalog by words, task, author, modality, price or context length	None	Free
`get_model`	Returns a model's details, endpoints, and measured uptime, latency and throughput	None	Free
`chat_completion`	Asks a language model, with fallback models, provider preferences and plugins such as web search	`llm.write`	Paid
`text_to_speech`	Speaks up to 4,096 characters, as a one-hour download link or inline audio	`audio.write`	Paid
`transcribe_audio`	Transcribes audio from a public HTTPS URL or base64, up to 25 MB	`audio.write`	Paid
`generate_image`	Generates one 1024×1024 image and returns it as an image	`images.write`	Paid
`get_key_info`	Shows the key's scopes, limits and expiry, and the workspace's remaining credit	None	Free
`get_usage`	Lists settled usage and cost, newest first	`usage.read`	Free
`list_requests`	Lists recent requests with model, state, latency and cost, never prompts or outputs	`requests.read`	Free
`search_docs`	Searches this documentation and returns passages with links	None	Free

Each tool calls the API endpoint it mirrors, so its inputs, limits and model IDs are the ones documented for that endpoint. A key without a tool's scope does not see the tool.

Costs

A paid tool call is the same funded request as the API call it makes, charged at the model's normal price. It holds funds for its largest possible cost, settles at the actual cost and appears in list_requests and get_usage; the tool's result reports what it cost. chat_completion holds funds for max_tokens, which defaults to 2,048.

Agents can call tools many times in one task. Keep your client's approval prompts on for the paid tools, and give each client's key a spending limit.

Security

The key is a bearer credential. Give each client its own key with only the scopes it needs, a spending limit and an expiry, and revoke it in the dashboard if a configuration file leaks.
The server refuses requests from web pages (any Origin header other than AudioLab's own) and dashboard sessions.
A speech link works for anyone who has it, for one hour. The audio is kept in the workspace's storage like other generated audio. When the workspace turns off audio storage or uses zero data retention, text_to_speech refuses a link before charging and returns audio only with delivery: "inline".
transcribe_audio downloads only from public HTTPS addresses, without credentials or redirects.
Tool results can contain text written by models and web pages. Treat them as untrusted input, as you would a web page an agent reads.

Errors and Limits

A failed tool call returns a result with isError: true and the API's error in structuredContent.error: status, code, message, param and request_id, as described in Errors and Debugging. An unknown tool name is a JSON-RPC error instead. Each MCP request counts once against the key's rate limit, and a request body may carry at most a 25 MB file as base64.