---
url: https://flat.io/developers/docs/mcp/tools.md
description: >-
  The tools exposed by the Flat MCP server - search, score_get, score_export and
  score_create - with their inputs, outputs, limits and errors.
---

# 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) | Search | read-only, idempotent |
| [`score_get`](#score-get) | Score: Get Details | read-only, idempotent |
| [`score_export`](#score-export) | Score: Export Notation | read-only, idempotent |
| [`score_create`](#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**

```json
{
  "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**

```json
{
  "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](/api/rate-limits), per client and
per customer, over a one-hour window. When it is exceeded, tools fail with `API_RATE_LIMIT_EXCEEDED`.