Docs · MCP server

The MCP server

MCP is the standard way to hand a tool to an AI client. Once THIRI is plugged in, you talk to Claude like normal; when the question is about harmony, Claude calls THIRI instead of guessing.

Updated 2026-10-02

The five tools

Tool	REST equivalent	What it does
`analyze_chord`	`/v2/analyze`	Chord symbol or notes → root, quality, intervals, scales, and (with a key) roman numeral and function.
`resolve_chord`	`/v2/resolve`	Chord → spelled notes, semitones, MIDI numbers, frequencies in Hz, recommended scales.
`generate_voicing`	`/v2/voicing`	Instrument-ready voicing (rootless, drop-2, shell, quartal…) with voice-leading from the previous chord.
`reharmonize`	`/v2/reharmonize`	Up to eight reharmonization alternatives for a progression, each explained.
`conduct_band`	`/v2/conduct`	A text direction → conductor, four lanes of note events, lead sheet and a MIDI file.

Arguments mirror the REST fields. Responses are the same JSON, so anything you learn on one surface transfers to the other.

Interactive MCP Tool Playground

Try all five tools right here before connecting Claude or Cursor. 100% computed in-browser with zero latency, real-time geometric pitch-class polygon rendering, and Web Audio auditioning.

MCP HOSTED & STDIO THIRI Chord Intelligence Sandbox

DETERMINISTIC: 100% LATENCY: 0.6ms MODEL: PITCH-CLASS-SET

CHORD / ROOT

Dm9 (D)

ROMAN NUMERAL

ii9 (C)

HARMONIC FUNCTION

PREDOMINANT

Mod-12 Harmonic Constellation

Root Guide (3/7) Tension

ACTIVE VOICING NOTES:

Local (stdio) via npx

The package on npm is @bluesprincemedia/thiri-mcp. Clients start it for you; to run it by hand:

terminal

THIRI_API_KEY=YOUR_KEY npx -y @bluesprincemedia/thiri-mcp

Speaks MCP over stdin/stdout. Your key never leaves your machine except as a bearer token to chords.thiri.ai.

Client configs are on the install page. The shortest one is Claude Code:

Claude Code

claude mcp add thiri --env THIRI_API_KEY=YOUR_KEY -- npx -y @bluesprincemedia/thiri-mcp

Hosted (remote) at mcp.thiri.ai

For clients that cannot run a local process, such as Claude on the web and on mobile, use the remote server. Add it as a custom connector with the URL below and your key as the bearer token.

remote MCP endpoint

https://mcp.thiri.ai/mcp

JSON-RPC over HTTP. A GET to the endpoint answers 405 (POST and OPTIONS only) and a GET to the host root is 404; neither means it is down.

A system prompt that keeps the agent honest

Models are good at intent and bad at arithmetic over pitch classes. The tool only helps if the model reaches for it. Put this (or your version of it) in your system prompt, your Claude Project, or your CLAUDE.md:

system prompt

You have the THIRI tools. For any question that involves chords, keys,
scales, voicings, progressions or arrangements, call THIRI before answering
and base your answer on what it returns. Quote the notes THIRI gives you.
Do not spell chords from memory.

In a chat, the lightweight version is to start the message with "Using THIRI,". In Claude Code, a CLAUDE.md line does the same job for every session.

Recipes

Connecting a music-theory MCP to Claude: the first wiring, step by step.
22 ways to build with the THIRI MCP server: prompts, configs and agent workflows.
Agent recipes: the Csound loop, where THIRI supplies the harmony and a second MCP renders the audio.
Ableton Live connector: THIRI inside a Max for Live device.

Source, licence and versions

The server's source is at github.com/BluesPrince/thiri-mcp. Recent releases are licensed under PolyForm Noncommercial 1.0.0 (free for non-commercial use; talk to us for commercial embedding); earlier releases were MIT. The LICENSE file in the version you install is authoritative. The engine behind the API is not part of the package. Releases are listed on the changelog. Pin a version in production (npx -y @bluesprincemedia/thiri-mcp@0.5.3) if you want to control when you pick up changes.

Keys, tiers and limits →

What a free key gets you, what Builder adds, and how rate limits behave.