THE TUNINGS DEVELOPER API v1

Music theory.
Ready to build on.

Tunings, notes, scales, and fretboard positions.
The engine behind Tunings, ready for your next app.

REST + MCP. Predictable results. Your interface.

One request. A new tuning.POST

curl https://api.tunings.io/v1/transpose \
  -H "Authorization: Bearer $TUNINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": ["D2","A2","D3","G3","B3","E4"],
    "semitones": -2
  }'

Transpose Drop D

RESULTING OPEN STRINGS

C2STRING 1
G2STRING 2
C3STRING 3
F3STRING 4
A3STRING 5
D4STRING 6

Interactive preview · computed locally with the Tunings engine

The same engine as Tunings

Custom tunings

Up to 12 strings · 36 frets

Versioned REST endpoints

THE MUSICAL BUILDING BLOCKS

Your product. Our music engine.

From a tuning lookup to a custom fretboard,
start with the pieces you need.

Start with any tuning.

Discover instrument presets and alternate tunings, or bring your own open-string pitches.

GET /v1/tunings

Map the whole fretboard.

Turn a tuning into notes and positions. Add a root and scale to find exactly where they belong.

POST /v1/fretboard

Move an idea anywhere.

Transpose notes, explore chord positions, and build scale tools with deterministic results.

POST /v1/transpose

API REFERENCE

A small surface.
A lot to play with.

Send a request. Get structured music data back. Use the OpenAPI specification for request schemas, response types, and examples.

Download OpenAPI 3.1

REST BASE URLhttps://api.tunings.io/v1

MCP · STREAMABLE HTTPhttps://api.tunings.io/mcp

MCP exposes the same eleven music operations to compatible assistants. Configure the URL above and your Bearer key in your client’s private settings. REST and MCP share your account limits.

Every music endpoint requires a Bearer API key and paid developer access. Check the public health endpoint ↗

GET/health

Check API health and version. No key required.

GET/instruments

Browse supported instrument definitions.

GET/instruments/{instrumentId}

Get an instrument and its default tuning.

GET/tunings

Filter by instrument, string count, category, or search.

GET/tunings/{tuningId}

Get open-string pitches, aliases, and intervals.

POST/fretboard

Generate notes and positions for a custom tuning.

GET/scales

Browse supported scale types.

GET/scales/{scaleId}

Build a scale with an optional root, such as ?root=E.

POST/scales/map

Find scale positions across your fretboard.

GET/chords

Browse supported chord definitions.

POST/chords/voicings

Enumerate bounded mathematical chord positions.

POST/transpose

Shift notes or a tuning by a number of semitones.

CONNECT YOUR ASSISTANT

Tunings, inside your workflow.

Eleven music tools. The same developer key.
Choose your client below.

1. Create API key

Open Account → API keys, click Create API key, and give it a name. Active paid developer access is required.

Create API key →

2. Add to MCP

In Connect an MCP client, choose your client and copy its configuration before dismissing the new key. Paste it into your client’s private user settings, then restart the client. Your key is already included.

https://api.tunings.io/mcp

Advanced: use an environment variable instead

Make your existing key available to the client

In macOS or Linux Bash/Zsh, paste your key at this hidden prompt. It stays out of shell history. Launch your client from this same terminal; repeat this step in a new shell.

printf 'Tunings API key: '
read -r -s TUNINGS_API_KEY
printf '\n'
export TUNINGS_API_KEY

Keep the variable placeholders in the examples unchanged. Never paste your key into chat or commit it to a configuration file. Desktop apps must inherit the variable when they start; an already running app may need a full restart. In SSH, containers, or remote workspaces, set it where the MCP client runs.

Configure your client

Claude Code

Run this once to add Tunings to your user configuration. The single quotes preserve the environment placeholder.

claude mcp add-json --scope user tunings \
  '{"type":"http","url":"https://api.tunings.io/mcp","headers":{"Authorization":"Bearer ${TUNINGS_API_KEY}"}}'
claude mcp list

Expect Connected. Start claude in the same terminal and use /mcp to inspect Tunings and its tools. Claude Code documentation ↗

Codex

Run this once. Codex stores the environment variable name, leaving the key in your environment.

codex mcp add tunings \
  --url https://api.tunings.io/mcp \
  --bearer-token-env-var TUNINGS_API_KEY
codex mcp get tunings

Or merge this entry into ~/.codex/config.toml:

[mcp_servers.tunings]
url = "https://api.tunings.io/mcp"
bearer_token_env_var = "TUNINGS_API_KEY"

Start codex in the same terminal and use /mcp to inspect Tunings. The get command checks configuration, not connectivity. Tunings uses your key, so no MCP OAuth login is needed. Codex documentation ↗

Cursor

Merge this entry into ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project. Preserve any existing servers.

{
  "mcpServers": {
    "tunings": {
      "url": "https://api.tunings.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TUNINGS_API_KEY}"
      }
    }
  }
}

Fully quit Cursor, then launch it from the terminal containing your key with cursor .. Enable Tunings in MCP settings and check the tools list. Remote connections use the inherited environment; Cursor’s envFile setting only applies to local stdio servers. Cursor documentation ↗

VS Code

Run MCP: Open User Configuration from the Command Palette, or merge this into .vscode/mcp.json for one workspace. Preserve existing servers.

{
  "servers": {
    "tunings": {
      "type": "http",
      "url": "https://api.tunings.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TUNINGS_API_KEY}"
      }
    }
  }
}

Fully quit VS Code and launch with code . from the terminal containing your key. Run MCP: List Servers, select Tunings, and start it. Review the trust prompt and enable its tools in chat. VS Code documentation ↗

Check your connection

Ask your assistant: “Use Tunings transpose_tuning to transpose D2 and A2 down two semitones.” Approve the tool call when prompted. Confirm the actual tool result contains C in octave 2 and G in octave 2. Also try get_tuning with {"tuningId":"drop-c"}.

Connection troubleshooting

401: Check the key, revocation status, and the client’s environment. Claude uses ${TUNINGS_API_KEY}; Cursor and VS Code use ${env:TUNINGS_API_KEY}.
403: The account needs active paid developer access, or the client’s browser origin is not allowed. Contact support with the request ID.
429: Respect Retry-After. Connection, discovery, and tool requests share your REST quota.
405 in a browser: Opening the MCP URL performs a GET. Connect through your MCP client; use the health endpoint for a browser check.
OAuth prompt or missing tools: Check the endpoint and Authorization configuration, restart the client, and review its logs locally. OAuth-only clients are not supported. These Claude Code instructions do not configure Claude.ai or Claude Desktop connectors.

A FEW THINGS TO KNOW

Built for real integrations.

01 / AUTHENTICATION

A key for your backend.

Send your key in the Authorization header. Keep it on your server and out of browser bundles.

Authorization: Bearer tun_live_…

02 / PREDICTABLE DATA

Inputs in. Music data out.

Scientific pitch notation, explicit octaves, and deterministic calculations. Object responses use data; collections add pagination metadata.

03 / REQUEST LIMITS

Clear limits. Useful feedback.

Responses include rate and quota headers. A 429 response includes Retry-After, so your integration knows when to try again.

LET’S BUILD SOMETHING MUSICAL

Build with Tunings Pro.

Add the REST API and MCP tools to your Tunings membership for $19.99 USD/month plus applicable tax.

Upgrade to Pro

250,000 requests per month and up to 10 requests per second. Contact support for higher-volume plans.

01
Upgrade to Pro
$19.99 USD/month plus applicable tax for the app, API, and MCP tools.
02
Create your API key
Open Developer in your account and create a key after your payment is confirmed.
03
Connect your tools
Use your key with the REST API or copy the configuration for your MCP client.

Before you build.

Is this included in my Tunings subscription?

Tunings Pro includes the app, REST API, and MCP tools for $19.99 USD/month plus applicable tax. The $9.99 Early Access plan covers the app. Existing subscribers can upgrade their current subscription in their Developer account page.

Can I use the API directly from a browser?

Use your own backend to keep your secret API key private. Browser origins must also be explicitly allowed; CORS does not protect a key embedded in frontend code.

Are SDKs, translation, and MCP available?

REST and MCP use the same paid developer access. MCP requires a remote client that supports an Authorization header; OAuth sign-in and stdio connections are not supported yet. Dedicated SDKs and translation endpoints are also not available yet.

Does the API rank chord shapes by playability?

Chord voicings return bounded mathematical positions. They are not ranked by fingering difficulty or musical suitability; inspect the returned limits and truncation information.

What if I only need public reference data?

The reference library is free to browse. Programmatic catalog access requires a developer key and paid developer access, just like custom calculations.

Music theory.Ready to build on.