---
url: https://flat.io/developers/docs/mcp.md
description: >-
  Connect AI assistants and agents to a Flat account with Flat's remote MCP
  server. Endpoint, requirements, supported clients and how access works.
---

# Flat MCP server

::: tip Using ChatGPT or Claude?
You do not need this page. Follow the step-by-step guides in the help center:
[ChatGPT](https://help.flat.io/en/ai/chatgpt), [Claude](https://help.flat.io/en/ai/claude), or
[what your assistant can do with Flat](https://help.flat.io/en/ai/connect).
:::

Flat runs a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI
assistants and agents can work with the sheet music in a Flat account: search the customer's
scores and collections, read their details and notation, and create new scores.

```
https://mcp.flat.io/mcp
```

Add this URL to your assistant. The first time it connects, it sends you to Flat to sign in and
approve the access.

## Connect your assistant {#connect}

### Claude and ChatGPT

* **Claude** (claude.ai and the desktop app): open
  [Settings > Connectors](https://claude.ai/settings/connectors), click **Add** then **Add custom
  connector**, and paste the URL. Keep the detected sign-in options and click **Add**, then
  **Connect**. [Step-by-step guide with screenshots](https://help.flat.io/en/ai/claude).
* **ChatGPT**: open [chatgpt.com/plugins](https://chatgpt.com/plugins), click **Add** then **Add
  custom MCP server**, paste the URL and choose **OAuth**. Works on every ChatGPT plan, including
  the free one. [Step-by-step guide with screenshots](https://help.flat.io/en/ai/chatgpt).

### Coding assistants and editors

Run the command or add the configuration below. The client opens Flat's sign-in page in your
browser the first time it connects.

::: code-group

```bash [Claude Code]
claude mcp add --transport http flat https://mcp.flat.io/mcp
```

```bash [Codex]
codex mcp add flat --url https://mcp.flat.io/mcp
codex mcp login flat
```

```bash [Gemini CLI]
gemini mcp add --transport http --scope user flat https://mcp.flat.io/mcp
```

```jsonc [Cursor]
// ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
  "mcpServers": {
    "flat": {
      "url": "https://mcp.flat.io/mcp"
    }
  }
}
```

```jsonc [VS Code]
// .vscode/mcp.json, or "MCP: Open User Configuration" for every project
{
  "servers": {
    "flat": {
      "type": "http",
      "url": "https://mcp.flat.io/mcp"
    }
  }
}
```

:::

Any other client that supports remote MCP servers with OAuth works the same way: give it the URL.

## At a glance

* **Endpoint**: `https://mcp.flat.io/mcp`
* **Transport**: Streamable HTTP, stateless (no SSE endpoint)
* **Authorization**: OAuth 2.1 with PKCE (`S256`), single scope `mcp`. See [Authorization](./authorization)
* **Client registration**: Client ID Metadata Documents (preferred) or Dynamic Client Registration
* **Tools**: `search`, `score_get`, `score_export`, `score_create`. See [Tools](./tools)
* **Who can connect**: Flat accounts with an active Flat Power subscription

There is no API key or personal token for the MCP server: every connection goes through Flat's
OAuth consent screen, where the customer approves the client by name.

## Requirements

* **Remote MCP over HTTP.** Clients connect to `https://mcp.flat.io/mcp` directly; there is
  nothing to install.
* **OAuth sign-in.** The client must support the MCP authorization flow (protected resource
  metadata, PKCE). Clients that only accept a static token or a password cannot connect.
* **An eligible Flat account.** Connecting requires an active
  [Flat Power](https://flat.io/pricing) subscription. Flat for Education accounts cannot connect
  yet. Eligibility is checked at consent and again on every request, so a lapsed subscription
  stops access on the next call.

## What a connected client can do

| Tool | Access | What it does |
|---|---|---|
| `search` | Read | Search the customer's own scores and collections |
| `score_get` | Read | Get one score's metadata: title, composer, instruments, duration, link |
| `score_export` | Read | Get a score's notation as MusicXML, compressed MusicXML or MIDI |
| `score_create` | Write | Create a new private score from MusicXML, MIDI, ABC, MuseScore or Guitar Pro |

The server never edits or deletes an existing score, and never makes a score public: transposing
or arranging produces a new score. Scores outside the customer's account are not reachable. Full
schemas are on the [Tools](./tools) page.

## Recognized clients

Flat recognizes ChatGPT, Claude and Visual Studio Code. The consent screen shows them with their
name and logo, marked as recognized by Flat. Any other client is shown with the name it declares
and how much Flat could verify about it; see [Consent screen](./authorization#consent-screen).

## You stay in control

* **You approve each assistant once, in Flat.** The consent screen names the app asking for access
  and the single permission it needs. Nothing is shared until you click **Allow access**.
* **Your assistant reads and creates, nothing more.** It cannot edit or delete an existing score,
  publish or share one, or change your account.
* **You can revoke access at any time** from your
  [account settings](https://flat.io/settings/account/profile), under **Link external accounts and
  apps**. Revoking deletes every token Flat issued to that assistant, and its next request fails.

## Support

Questions or problems with the MCP server: <developers@flat.io>.