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 same 15 tools that the built-in MidiPilot AI uses. 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 → AI Settings. 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.

{
  "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 15 tools from MidiEditor AI’s built-in MidiPilot are exposed via MCP. The AI client discovers them automatically via tools/list.

Read-Only Tools READ

Write Tools WRITE

FFXIV Tools FFXIV

These tools appear automatically when FFXIV mode is enabled in MidiEditor AI. 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.

Protocol Panel & Client Identification

Every tool call made via MCP appears in the Protocol panel with a special 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.

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 in MidiPilot settings

“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)