Skip to main content
Glama

plainsong-mcp

A Model Context Protocol server for Plainsong, so any agent can read, write and compile music notation — and so several agents can work on one score at the same time without overwriting each other.

plainsong-mcp                 # JSON-RPC over stdio, what most clients expect
plainsong-mcp --http          # loopback HTTP, for remote and multi-agent setups
plainsong-mcp --list-tools    # what it exposes

Install

pip install git+https://github.com/SuperInstance/plainsong-mcp

That brings in the compiler as well. Neither has any other dependency: the protocol, both transports, the session store and the compiler itself are written against the standard library. Python 3.10 or newer.

The compiler comes from PyPI as plainsong>=1.4.0. 1.1.0 is the first release carrying plainsong.features, the per-bar analysis this package re-exports rather than duplicating; 1.4.0 is the first carrying plainsong.runtime.localhost, the loopback check behind the same re-export, so 1.4.0 is now the binding floor. Either way the requirement is real: below it the install succeeds and the import fails.

Related MCP server: ableton-mcp-server

Point a client at it

For a client that launches servers over stdio, the usual shape is:

{
  "mcpServers": {
    "plainsong": {
      "command": "plainsong-mcp"
    }
  }
}

Then ask it for music. The server exposes 27 tools, which is everything the plainsong CLI can do — write and validate notation, compile to MIDI and audio, transpose, search a library of several thousand pieces, analyse what each listener on a stage actually hears, and probe what the host machine can render.

Many agents, one score

The reason this exists. A session gives every agent a voice of its own:

ensemble_open    name a session, set key, tempo and metre
ensemble_join    claim a voice -- one owner at a time
ensemble_read    the whole current state, in one call
ensemble_write_part   write your voice, against the version you read
ensemble_render  merge the parts and compile
ensemble_log     what everyone has done

Because the parts are disjoint, the common case never conflicts — two agents writing two voices both succeed. When two do collide, the later write is refused and handed the current state to rebase onto, rather than silently overwriting somebody's work. Locks are held only around a read-modify-write of the manifest, never across a call to a model, because a model call takes seconds and a lock held that long is a lock nobody else can get.

Notation is parsed before a part is accepted, so invalid notation never lands. Writes are atomic, the merge is deterministic, and every change appends to a log a joining agent can read to find out what has happened so far.

See docs/ensemble.md for the whole protocol and docs/mcp.md for the tool and resource surface.

Reading a score as features

analyze_features computes sixteen per-bar features — note density, harmonic tension, syncopation, contour direction, register spread and so on — matching the vocabulary fleet-jepa-midi perceives. That lets a bandleader read a written score, and makes a corpus of notation usable as labelled training data.

Three more instruments serve the perception loop directly, each closing a seam the pulse-eye retrospective found (tensor-midi, 2026-08-25): everything the loop needed was in the per-bar stream, and the summaries averaged it away.

  • perception_trace — the per-bar rows of a session, all sixteen channels, and deliberately no mean. A pocket lock was one bar among sixteen; a consumer that reads averages will never see it. analyze_features returns these rows too — the seam was never that the data was hidden, but that consumers collapsed it early.

  • perception_audit — variance and correlation over the sixteen channels, and a verdict per channel: DEAD (zero variance in the texture and every voice — a dial connected to nothing), COUPLED (|r| > 0.9 with another channel — one steering dimension, not two) or ALIVE. Orthogonality of steering channels is the difference between growing and stalling; the audit counts the degrees of freedom a loop actually has. Run against the seamstress gate-1 session it reads: 16 channels → 6 steering dimensions (7 dead, 4 coupled into 1) — register was the only live growth channel, which is what the growth curves had already shown.

  • dimension_stats — one named annotation row of a session (Breath:, Gaze:, anything a composer can write) as count, mean, std and a per-bar series, so an eye can see custom dimensions, not just velocity. This sits on a compiler capability that is not in a plainsong release yet: generic annotation rows live on the unmerged dynamics-and-swing branch of SuperInstance/plainsong (built on annotation-rows). On a compiler without it the tool answers with an error naming the missing capability, and a Breath: row in a part is kept as free text. Nothing is vendored; when the branch merges, the tool starts reading with no change here.

Where this came from

This began inside the compiler's repository and was extracted once it was clear it had become its own thing rather than a feature of the compiler. Two names had also collided along the way: the analysis of who hears what on a physical stage, and a session shared by several agents, were both called "ensemble". The first is now plainsong stage and lives with the compiler; the second is what this repository means by the word.

The compiler still ships a copy of this server, which is what its plainsong mcp command runs. That copy is being retired — install from here.

Status

The protocol is exercised by a test suite that drives the server with real JSON-RPC: the initialize handshake, tools/list, tools/call, malformed input, unknown methods, notifications, and a tool that raises. Concurrency is tested with threads racing for the same voice, and merge determinism is checked by writing the same parts in three different orders and comparing bytes rather than assuming.

CI runs the suite on Python 3.10 through 3.13 across Linux, macOS and Windows, and then speaks the protocol to the built server over a pipe, so a handshake that regresses fails the build rather than a mock of one.

No third-party MCP client has connected to it yet. The protocol behaviour is verified against the specification rather than against a particular client — strong evidence, and not the same thing. Doing that is the most useful thing anyone could contribute.

90 tests.

Licence

MIT. See LICENSE.

Available Tools

27 tools
analyze_featuresC

Describe a piece as sixteen numbers per bar -- density, register, tension, syncopation, dynamics and the rest -- so a model can perceive what is written.

Inputs: bars, path, table, voice, +2 more.

apply_directivesA

Apply a bandleader's directive JSON to a piece or an ensemble session and return the result as data: the directives as they were read, what the arrangement was before and after, and the sixteen features per bar of each. Use conduct_score instead when you want the timing report in prose.

Inputs: directives (required), path, frame, content, +2 more.

compile_scoreA

Compile notation to MIDI and audio, returning the arrangement summary and any diagnostics. Pass either a path or inline content.

Inputs: path, audio, content.

conduct_scoreA

Apply a bandleader's directive JSON to a piece and report what it did to the ensemble's timing: how the arrivals moved together and how far each player's hands moved to keep them there.

Inputs: directives (required), path, frame, content.

directive_referenceA

Read the conductor's directive vocabulary -- the JSON a bandleader sends, which actions the timing layer acts on, and what the windows and targets mean. Call this before writing directives for the first time in a session.

Inputs: no named parameters.

ensemble_joinA

Claim one voice of a session. A voice has one owner at a time, so claiming is how agents avoid choosing the same part. Returns everything needed to start writing.

Inputs: agent (required), voice (required), session (required), takeover.

ensemble_leaveB

Release a voice you hold so another agent can take it.

Inputs: agent (required), voice (required), session (required).

ensemble_logA

Read the session's change log, oldest first. This is how a joining agent finds out what has already happened.

Inputs: session (required), limit.

ensemble_openA

Open a shared session several agents can write to, or reopen one that exists. Sets the key, tempo, metre and form every part is written against.

Inputs: session (required), key, bars, meter, +5 more.

ensemble_readA

Read a session in one call: key, tempo, metre, form, which voices exist and who holds them, what every voice plays in the bars you are about to write, your own part, the version to write against, and what has changed recently.

Inputs: bars, agent, voice, history, +1 more.

ensemble_renderC

Merge the parts and compile the session to MIDI, and optionally audio.

Inputs: session (required), audio.

ensemble_reportA

Report what a listener on the stage actually hears: each voice's distance, speech time, propagation delay and the moment its player has to act, plus the spread at the chosen listener and at every other one.

Inputs: path, frame, content.

ensemble_statusA

The short view of a session: version, voices, who holds what, bar count and whether the merged score still compiles. Omit the name to list sessions.

Inputs: session.

ensemble_write_partA

Write your voice's part. The notation is parsed and checked against the session header before anything reaches disk. Pass the base_version you read; if the voice has moved on the write is refused and you are given the current part to rebase onto.

Inputs: agent (required), voice (required), content (required), session (required), +2 more.

list_filesB

List files in the working directory.

Inputs: path.

notation_referenceA

Read the TapScript notation reference. Call this before writing notation for the first time in a session.

Inputs: no named parameters.

probe_hostA

Report what this machine can do: platform, optional libraries, soundfonts, MIDI ports, audio playback, network. Use it before choosing how to render or connect.

Inputs: no named parameters.

read_fileB

Read a text file from the working directory or the project.

Inputs: path (required).

read_libraryB

Read one file from the bundled notation library, by name or title.

Inputs: name (required).

record_decisionB

Append a line to the build journal, recording a decision and why it was made.

Inputs: note (required).

search_libraryA

Search the bundled notation library for reference material by title, key or style.

Inputs: query (required), limit.

speech_profilesA

List the instrument speech profiles a [Stage] block can name, with how long each takes to sound and how far into the attack the ear places it.

Inputs: no named parameters.

stage_referenceA

Read how to write a [Stage] block: positions, listeners, speech profiles and feel. Call this before writing arrival-centric timing for the first time in a session.

Inputs: no named parameters.

transpose_scoreA

Transpose a notation file to another key, writing the result next to it.

Inputs: key (required), path (required).

verify_specsA

Run the project's specs and report what passes and what fails. Use this after making a change to check whether it worked.

Inputs: tag.

write_fileA

Write a text file into the working directory, creating parent directories.

Inputs: path (required), content (required).

write_scoreA

Write TapScript notation to a .tap file. The notation is parsed first and the result reports any problems, so use this rather than write_file for music.

Inputs: path (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes. A few pairs like apply_directives/conduct_score and compile_score/ensemble_render share similar actions but are differentiated by output format or input scope in their descriptions. ensemble_read and ensemble_status also overlap in state reporting but serve different detail levels. Overall, the descriptions help an agent distinguish them, though a couple of near-overlaps exist.

    Naming Consistency3/5

    The naming mixes several conventions: verb_noun tools (analyze_features, read_file, write_score), noun_reference tools (directive_reference, notation_reference, stage_reference), and an ensemble_ prefix group that itself mixes verbs and nouns (ensemble_join vs ensemble_status). While snake_case is consistent, the verb/noun ordering and prefix usage are not uniform, making the naming less predictable than a single pattern.

    Tool Count3/5

    With 27 tools, the server is on the heavy side. It covers a broad scope including notation, directives, ensemble collaboration, library access, file utilities, and build tasks. Many tools are general-purpose (list_files, read_file, write_file, probe_host, record_decision, verify_specs) and not core to music notation, but each has a clear role. The count feels borderline excessive rather than well-scoped.

    Completeness4/5

    The core workflow is well covered: writing, reading, compiling, transposing, and analyzing notation; applying directives; and full ensemble session lifecycle (open, join, write, render, report). References and library tools support learning, and file/build utilities round out the environment. Minor gaps like no explicit score deletion or directive update exist, but they can be worked around with existing tools.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A music MCP server enabling multi-agent collaboration where AI agents jam together in real-time, with 20 tools, conductor mode, and zero dependencies.
      141 npm
      39
      AGPL 3.0
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      MCP server for vibe coding with music, enabling format conversion (LilyPond, MusicXML, MIDI, ABC, etc.), audio-to-sheet transcription, and transposition with robust fallback outputs.
      1
      -