MCP · early access
AudioKit for agents
AI agents can use AudioKit through the Model Context Protocol. The MCP server is part of the API: the same API keys, the same validation and the same jobs as /v1, exposed as tools.
MCP is rolling out, in early access like the rest of AudioKit. Until it reaches your base URL, agents can call the HTTP API directly.
Connect
| Endpoint | POST https://api-production-cd43.up.railway.app/mcp |
| Transport | MCP Streamable HTTP, on the same host as |
| Authentication | Your AudioKit API key, as for the HTTP API: |
| Server | Name |
Any client that supports Streamable HTTP with a custom header can connect. In a client's JSON config:
{
"mcpServers": {
"audiokit": {
"type": "http",
"url": "https://api-production-cd43.up.railway.app/mcp",
"headers": { "Authorization": "Bearer ak_..." }
}
}
}
Or with Claude Code:
claude mcp add --transport http audiokit https://api-production-cd43.up.railway.app/mcp \ --header "Authorization: Bearer ak_..."
Input files
Files are passed as in the HTTP API: an https url AudioKit can download, plus the file's sha256. URLs must resolve to public addresses. See Before you start.
Tools
| Tool | Does |
|---|---|
| health | Service status and version, as |
| list_operations | Operations this instance can run, as |
| submit_job | Submit any job, as |
| get_job | A job's status and result, as |
| cancel_job | Cancel a job, as |
| tempo | BPM and beat grid |
| key | Musical key |
| fingerprint | AcoustID-compatible Chromaprint |
| analyze | Loudness, tempo, key, fingerprint and tags in one pass |
| tags | Genre, mood and vocals (CLAP). Listed only when the instance has the tag model |
There are no separate tools for probe, loudness, waveform, transcode or preview: use submit_job for those.
Service
health
No input. Returns {"status": "ok", "version": …}, as Health.
list_operations
No input. Returns {"operations": [{"operation", "outputs", "async", "requires_consent"}]}, as Capabilities.
Jobs
These mirror the HTTP API's job endpoints and return the Job.
submit_job
| Field | Type | Notes |
|---|---|---|
| operation | string | The operation to run. See operations. |
| input | object |
|
| paramsoptional | object | The operation's params. |
| outputsoptional | object |
|
| webhookoptional | object |
|
| authorizationoptional | object |
|
| job_idoptional | string | Your ID and the idempotency key, as in the HTTP API. Generated as |
| wait_secondsoptional | integer | How long to wait for the result. 0–300, default 0 |
get_job
| Field | Type | Notes |
|---|---|---|
| provider_job_id | string | AudioKit's ID for the job, from the Job. |
| wait_secondsoptional | integer | How long to wait for the job to finish. 0–300, default 0 |
cancel_job
| Field | Type | Notes |
|---|---|---|
| provider_job_id | string | The job to cancel. See Cancel a job. |
Analysis
Shortcuts for submit_job plus waiting: each submits its operation and waits for the result, 60 seconds by default. They take no webhook, outputs or authorization. Each returns the Job, with result as that operation's result in the reference.
All of them take:
| Field | Type | Notes |
|---|---|---|
| url | string | https URL of the input file. |
| sha256 | string | The file's sha256. |
| filenameoptional | string | As in InputFile. |
| job_idoptional | string | Your ID and the idempotency key. |
| wait_secondsoptional | integer | How long to wait for the result. default 60, max 300 |
tempo
BPM and beat grid. Result as tempo. Also takes the BPM search range, as TempoParams:
| Field | Type | Notes |
|---|---|---|
| min_bpmoptional | number | 40–300, default 70 |
| max_bpmoptional | number | 40–300, default 180 |
key
Musical key. No other fields. Result as key.
fingerprint
AcoustID-compatible Chromaprint. No other fields. Result as fingerprint.
analyze
Loudness, tempo, key, fingerprint and tags in one pass. Also takes min_bpm and max_bpm, as tempo. Result as analyze; tags is null when the instance has no tag model.
tags
Genre, mood and vocals (CLAP). Listed only when the instance has the tag model. Result as tags. Also takes:
| Field | Type | Notes |
|---|---|---|
| embeddingoptional | boolean | default false |
Output
A successful tool result carries the object in structuredContent, and the same object as JSON in its text content. Shapes match the HTTP API exactly: health returns Health, list_operations returns Capabilities, and every job tool returns the Job, as GET /v1/jobs/{id} does:
provider_job_id, job_id, operation, status queued | running | succeeded | failed | canceled result, error, provenance, created_at, started_at, finished_at
Waiting for results
wait_seconds holds the tool call open until the job finishes or the time runs out. It is 60 seconds by default on the analysis tools and 0 on submit_job and get_job, up to 300.
If the time runs out first, the Job comes back queued or running. That isn't an error: call get_job with its provider_job_id, optionally with wait_seconds, until it finishes.
Errors
A refused call is a tool result with isError: true and structuredContent holding the API's error body:
{ "error": { "code": "not_found", "message": "…" } }
The codes are the HTTP API's: invalid_request, operation_unavailable, idempotency_conflict, not_found and unavailable. Their meanings are in the reference. A missing or unknown key never reaches a tool: it gets HTTP 401 unauthorized, as described under Connect.
A failed job is not a tool error. It comes back as a Job with status: "failed" and error.code set to one of the job error codes.
Consent
list_operations reports requires_consent for each operation. Submitting a consent-gated operation without authorization is refused with invalid_request, through MCP as through /v1.
No operation is consent-gated today. The future voice tools will be.