The deterministic theory rail
for AI agents.

The five primitives

Same engine over REST at chords.thiri.ai and over MCP. Sit THIRI downstream of a generator when you need a chart an agent can trust.

Transports

Two ways to reach the same five tools. 796 monthly npm downloads for @bluesprincemedia/thiri-mcp. Verified identical responses over stdio and hosted HTTPS.

Keys: build.thiri.ai/keys. This page is the API reference. For live usage and quota, open the developer dashboard.

Parse any chord symbol into its root, quality, intervals, and extensions. When a key is provided, returns the chord's Roman numeral and harmonic function.

{
  "chord": "Dm7",
  "key": "C"
}

{
  "symbol": "Dm7",
  "root": "D",
  "quality": "minor7",
  "intervals": [0, 3, 7, 10],
  "extensions": [],
  "alterations": [],
  "bassNote": null,
  "numeral": "ii",
  "degree": 2,
  "diatonic": true,
  "function": "predominant",
  "scales": [
    { "name": "Dorian", "role": "primary" },
    { "name": "Aeolian", "role": "secondary" }
  ]
}

Resolves a chord symbol to its spelled-out notes, frequencies, MIDI numbers, and recommended improvisation scales.

{
  "chord": "Cm7"
}

{
  "root": "C",
  "quality": "m7",
  "notes": ["C", "Eb", "G", "Bb"],
  "intervals": ["1", "b3", "5", "b7"],
  "semitones": [0, 3, 7, 10],
  "frequencies": [261.63, 311.13, 392.0, 466.16],
  "midi": [60, 63, 67, 70],
  "scales": [
    {
      "name": "Dorian",
      "role": "primary",
      "semitones": [0,2,3,5,7,9,10],
      "degrees": ["1","2","b3","4","5","6","b7"],
      "character": "Minor but bright — the 6th lifts it."
    }
  ]
}

Generate instrument-ready voicings for a chord in a specified style. Supports voice leading from a previous voicing to ensure smooth transitions.

{
  "chord": "Dm7",
  "style": "rootless",
  "octave": 3,
  "previousNotes": ["E3", "G3", "Bb3", "D4"]
}

{
  "notes": ["F3", "A3", "C4", "E4"],
  "midi": [53, 57, 60, 64],
  "intervals": ["m3", "P5", "m7", "M9"],
  "template": "bill_evans_rootless",
  "voiceLeadingScore": 0.94,
  "style": "rootless",
  "chord": "Dm7"
}

Analyze a chord progression and generate reharmonization suggestions. Returns per-bar substitution options with explanations, plus complete alternative progressions.

{
  "bars": ["Cmaj7", "Dm7", "G7", "Cmaj7"],
  "key": "C"
}

{
  "original": ["Cmaj7", "Dm7", "G7", "Cmaj7"],
  "key": "C",
  "suggestions": {
    "0": [{
      "name": "Secondary Dominant",
      "chords": ["A7"],
      "explanation": "A7 targets Dm7 as its V7...",
      "adventurousness": 2,
      "genres": ["jazz", "pop"]
    }]
  },
  "alternatives": [
    {
      "name": "Tritone Subs",
      "bars": ["Cmaj7", "Dm7", "Db7", "Cmaj7"],
      "adventurousness": 4
    },
    {
      "name": "Dark Mode",
      "bars": ["Cmaj7", "Fm7", "G7", "Cmaj7"],
      "adventurousness": 5
    }
  ]
}

MCP Server

THIRI ships an MCP server alongside the REST API. Any MCP-compatible client — Claude Desktop, Cursor, custom agents — can reach into the engine directly without writing HTTP plumbing. Two ways to connect: hosted (one-click, nothing to install) or local (npm/stdio).

Hosted — custom connector (Claude Desktop / web / mobile)

No install, no config file. In Claude: Settings → Connectors → Add custom connector, then paste the URL below. Claude registers itself and opens the THIRI consent page — paste your sk_live_ key once and the five tools appear.

Authenticated with your existing THIRI key (key-as-credential OAuth) — same key, same monthly quota as REST and the npm client.

Local — npm / stdio config (Claude Code, Cursor)

{
  "mcpServers": {
    "thiri": {
      "command": "npx",
      "args": ["-y", "@bluesprincemedia/thiri-mcp"],
      "env": {
        "THIRI_API_KEY": "sk_live_your_key"
      }
    }
  }
}

Available tools

Same engine, same auth, same rate limits as the REST API. Use MCP when you want the engine inside an agent loop; use REST when you want it inside an app.

Error Handling

All endpoints return standard HTTP status codes.

{
  "error": "invalid_chord",
  "message": "Could not parse chord symbol: Xmaj99"
}