MCP Server - Model Context Protocol

MidiEditor AI includes a built-in MCP (Model Context Protocol) server that lets any MCP-compatible AI client - Claude Desktop, VS Code Copilot, Cursor, Windsurf, Continue, and others - directly use MidiEditor’s MIDI editing tools. Instead of copy-pasting between your AI client and the editor, the AI can read your MIDI file, create tracks, insert notes, set tempo, and more - all through a standard protocol.

Protocol panel showing MidiPilotMCP actions with client identification

What is MCP?

The Model Context Protocol is an open standard that lets AI models discover and use external tools. Think of it like a USB port for AI - any AI client that speaks MCP can plug into MidiEditor AI and control it.

MidiEditor AI’s MCP server exposes the 32 core tools that the built-in MidiPilot AI uses, plus a switch_document tool of its own - and the six FFXIV tools whenever FFXIV mode is enabled. The difference is that with MCP, you choose which AI client and model to use.

Demo & Examples

See MidiEditor AI's MCP server in action with this AI-composed metal remix of Mozart's Eine kleine Nachtmusik - created using the MCP protocol with shredding guitars, strings, and drums:

Metal remix composition in MidiEditor AI

Protocol panel showing MCP agent actions

Listen & Download:

This demo shows how an external MCP client (Claude, VS Code Copilot, Cursor, etc.) can compose music by calling MidiEditor AI's tools. All 20 measures were created via the MCP protocol with a guitar solo in the middle.

Quick Start

1. Enable the MCP Server
   Go to Edit → Settings → MidiPilot AI. In the MCP Server section, check “Start MCP server on launch”. Optionally generate an auth token for security.
2. Copy the Config
   Click “Copy MCP Config to Clipboard”. This copies a ready-to-paste JSON snippet with the URL, port, and auth token.
3. Paste into Your AI Client
   Add the JSON to your client’s MCP configuration file (see Client Setup below).
4. Restart Your AI Client
   The MCP server starts immediately when you check the box in Settings. Just restart your AI client (Claude Desktop, VS Code, Cursor, etc.) so it connects to the running server.
5. Start Editing
   Open a MIDI file in MidiEditor AI, then ask your AI client to compose, edit, or analyze. All changes appear live in the editor with full undo support.

MCP Server settings - enable, configure port, generate auth token, copy config

Toolbar Toggle Button

You can also start and stop the MCP server directly from the toolbar without opening Settings. The MCP Server button shows the server status at a glance:

Green - MCP server is running and accepting connections

Gray - MCP server is stopped

Click the button to toggle the server on or off. The toolbar button stays in sync with the checkbox in Settings. You can reposition or hide it via Edit → Settings → Layout → Customize Toolbar.

Client Setup

Click “Copy MCP Config to Clipboard” in MidiEditor AI’s settings, then paste it into the appropriate config file for your AI client.

What lands on the clipboard is a single server entry named midieditor, carrying the url for the port you configured and - if you generated one - an Authorization: Bearer header. Every client below wraps that entry in its own key (mcpServers, mcp.servers, …); the entry itself is the same everywhere. Without a token the headers block is simply absent.

{
  "mcpServers": {
    "midieditor": {
      "url": "http://localhost:9420/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

// settings.json
{
  "mcp": {
    "servers": {
      "midieditor": {
        "url": "http://localhost:9420/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN_HERE"
        }
      }
    }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "midieditor": {
      "url": "http://localhost:9420/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "midieditor": {
      "url": "http://localhost:9420/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "midieditor": {
      "url": "http://localhost:9420/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Available Tools

All 32 core tools from MidiEditor AI’s built-in MidiPilot are exposed via MCP - including the document tools list_documents, get_document_overview and import_tracks_from_document and the file tools that create, open, save and close documents - plus MCP’s own switch_document, and the six FFXIV tools below when FFXIV mode is on. The AI client discovers them automatically via tools/list. A client that keeps its own copy of the tool list refreshes it by calling tools/list again after FFXIV mode was switched.

A tool call that names a parameter the tool does not have is refused with an error that lists the tool's parameters, and nothing is changed.

Each MCP connection works on one document at a time. The session binds to the document that is active when it first acts, and stays on it - so a read followed by an edit lands on the same document even if you switch tabs in the editor meanwhile. Call get_editor_state to point the session at whichever document is currently active, or use list_documents / switch_document to change the editor's active tab first (followed by get_editor_state to bind the session to it).

Read-Only Tools READ

Document Tools WRITE

The built-in MidiPilot agent has its own variant of switch_document that re-binds its run without changing the visible tab; the MCP tool described here always brings the chosen tab to the front in the editor window.

new_document and open_document bring the new tab to the front but leave the session bound to its document; call get_editor_state to work on the new one. They and close_document also work after the session’s own document was closed.

Saving: an MCP client writes over the MIDI file you opened only when you answered its question with "overwrite" (or the AI saves your file setting says so). Every other file it saves carries the mark .mcp and the extension .mid, whatever name it passes; a taken name gets a counter (mozart.mcp.2.mid), and its own marked working copy is saved in place. Saving is not an undo step. The full rules are on Saving and opening documents.

Write Tools WRITE

FFXIV Tools FFXIV

These tools appear automatically when FFXIV mode is enabled in MidiEditor AI - either via the FFXIV checkbox in the MidiPilot panel or by the AI client itself calling set_ffxiv_mode. The server sends a notifications/tools/list_changed notification when FFXIV mode is toggled, so connected clients refresh their tool list automatically.

MCP Resources

MCP resources provide read-only context. AI clients can read these to understand the current editor state without making tool calls. A resource read follows the same document the session’s tool calls act on, so state and edits stay in step even if you switch tabs in the editor meanwhile.

Protocol Panel & Client Identification

Tool calls that change the file are recorded in the Protocol panel, and the entry starts with a prefix that identifies the source client. During the MCP initialize handshake, the client sends its name and version in the clientInfo field. MidiEditor AI displays this in the Protocol panel:

• Built-in MidiPilot: MidiPilot: Agent insert events - Flute (20)
• MCP (with client info): MidiPilotMCP (VS Code Copilot Claude Opus 4.6): Agent insert events - Flute (20)
• MCP (without client info): MidiPilotMCP: Agent insert events - Flute (20)

This makes it easy to see which actions came from where - especially useful when both the built-in MidiPilot and an external MCP client are used on the same file. Every MCP action supports Ctrl+Z undo, just like built-in actions.

Every MCP tool call also shows a short line in the status bar with the client name and the tool - for a file operation with the path, for a failed call with the error. Reads and file operations appear there even though they add nothing to the Protocol panel.

Protocol panel - MCP actions with client name and model identification

Security

The MCP server is designed for local use only:

For personal use on your own machine, the server is safe without an auth token since it only accepts local connections. If you share your machine or want defense in depth, generate a token in Settings.

Limits & Performance

The MCP server enforces rate limits and has practical performance boundaries. AI clients should be aware of these when composing or editing large MIDI files.

Best Practices for Large Compositions

• Split insert_events calls into chunks of 4-8 measures per call for fast, reliable inserts
• For a full song, insert one track at a time rather than all tracks in one call
• Always include a program_change event at tick 0 when inserting into a new track
• Use query_events to verify inserts rather than re-reading the entire file state
• If you hit the rate limit, wait a moment and retry - the limit resets every 60 seconds

Troubleshooting

Server won’t start

• Check that port 9420 (or your configured port) is not already in use
• Try a different port in Settings (any value from 1024 to 65535)
• Make sure “Start MCP server on launch” is checked and you’ve restarted the app

Client can’t connect

• Verify MidiEditor AI is running and the MCP server is enabled
• Check that the port matches between MidiEditor settings and your client config
• If using an auth token, verify the token matches exactly (use “Copy MCP Config”)
• Some clients need a restart after config changes

Tools not showing up

• Make sure a MIDI file is loaded in MidiEditor AI (open or create a new file)
• For FFXIV tools, verify FFXIV mode is enabled - either via the FFXIV checkbox in the MidiPilot panel, or by calling set_ffxiv_mode from the client itself
• The server announces the change with notifications/tools/list_changed, but a client only receives it while an SSE stream is open. If your client shows a stale list, ask it to refresh the tools or reconnect

“Rate limit exceeded” error

• The server allows 100 tool calls per minute per session
• Wait a moment and retry - the limit resets every 60 seconds

Technical Details

Session Lifecycle

1. Client sends POST /mcp with initialize
2. Server responds with capabilities and Mcp-Session-Id header
3. Client includes Mcp-Session-Id in all subsequent requests
4. Client optionally opens SSE stream via GET /mcp
5. Client sends DELETE /mcp to end session (or it expires after 1 hour)