Tools

The Flat MCP server exposes four tools. Their names are stable. Every result is returned both as structuredContent and as JSON text in content[0].text.

Tool	Title	Annotations
search	Search	read-only, idempotent
score_get	Score: Get Details	read-only, idempotent
score_export	Score: Export Notation	read-only, idempotent
score_create	Score: Create	write, not idempotent

All tools act on the connected customer's own account only.

search

Search the customer's own scores and collections. Use it to find something the customer refers to before acting on it.

Input

Parameter	Type	Required	Description
query	string, max 500	yes	Natural-language or keyword search. Matches titles, composers, instrumentation and content
contentTypes	array of scores, collections	no	Defaults to both
limit	integer, 1-50	no	Defaults to 20

Output

{
  "totalHits": 2,
  "results": [
    {
      "type": "score",
      "id": "...",
      "title": "Nocturne in E flat",
      "url": "https://flat.io/score/...",
      "composer": "Frédéric Chopin",
      "modificationDate": "2026-10-06T08:12:00.000Z",
      "instruments": ["piano"],
      "collaborators": 0
    }
  ]
}

Every result has a type (score or collection). No match is a successful empty result.

score_get

Get the descriptive details of one score. Returns metadata only, never the notation: use score_export for the music itself.

Input

Parameter	Type	Required	Description
scoreId	string	yes	Score identifier, as returned by search or score_create

Output

id, title, composer, privacy, url, creationDate, modificationDate, instruments, instrumentsNames, durationTime (seconds), numberMeasures and collaborators (a count).

score_export

Get the notation of a score.

Input

Parameter	Type	Required	Description
scoreId	string	yes	Score identifier
revisionId	string	no	Defaults to the latest revision
format	musicxml, mxl, midi	no	Defaults to musicxml
inline	boolean	no	For midi only: return the file inline instead of a URL

Delivery

• musicxml and mxl are always returned inline. musicxml is UTF-8 text, mxl is base64.
• midi returns a short-lived download URL by default, or base64 inline with inline: true.
• Inline content is capped at 256 KiB. A midi file over the cap falls back to a URL. A musicxml export over the cap fails with PAYLOAD_TOO_LARGE: retry with mxl, the same notation compressed. Content is never truncated.

Output

Field	Description
scoreId, revisionId	The exported score and revision
format	musicxml, mxl or midi
delivery	inline or url
data, encoding	Inline content, utf-8 or base64
url, expiresAt	Download URL and its expiry, for delivery: url
sizeBytes	Size of the file
note	Present when the delivery differs from the request

score_create

Create a new score in the customer's account from notation you provide, and return a link to it. Prefer MusicXML: it is the only format that preserves all notation detail.

Input

Parameter	Type	Required	Description
title	string, max 255	yes	Title shown in the customer's library
format	musicxml, mxl, midi, abc, musescore, guitarpro	yes	Format of data
data	string, max 20,000,000 characters	yes	Plain text for musicxml and abc, base64 for the binary formats
encoding	base64	for binary formats	Required with mxl, midi, musescore and guitarpro
privacy	private, privateLink	no	Defaults to private

• abc is converted to MusicXML on import.
• midi keeps only pitches, timing and instruments.
• Scores cannot be created public. A privateLink score can be opened by anyone with its link.
• Created scores are filed in a collection dedicated to the connected client.

Output

{
  "status": "created",
  "id": "...",
  "title": "Morning Study",
  "url": "https://flat.io/score/...",
  "privacy": "private"
}

Large imports can still be running when the call returns. The result is then { "status": "processing", "taskId": "...", "message": "..." }, and the score appears in the customer's library when the import finishes.

Errors

A failed call returns a tool result with isError: true. The message is the API's, localized to the customer's language, and names the parameter at fault when there is one. The result also carries errorCode, errorParam and errorId (quote errorId when you contact us).

• A score that does not exist and a score the customer cannot access both return the same not-found error.
• Server-side failures return "Something went wrong on Flat's side. Try again shortly."

Rate limits

Requests count against the connected customer's API rate limit, per client and per customer, over a one-hour window. When it is exceeded, tools fail with API_RATE_LIMIT_EXCEEDED.