MCP server for AI agents

Advanced reference

For people who use an AI assistant that supports the Model Context Protocol.

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call tools offered by a local program. gsplit-mcp is the GSplit program that offers such tools: an assistant such as Claude Code or Claude Desktop can split a file, look at a piece set, verify it and join it back, using the same engine as the window and gsplitc.

gsplit-mcp (gsplit-mcp.exe on Windows) is installed next to GSplit.exe. It is a console program that talks MCP over standard input and output; you do not start it yourself, your MCP client does. It has no window and needs no WebView2.

When you need this reference

This guide is for connecting an AI agent to GSplit. You can split and restore files directly in the app without this setup; start with Getting started.

Install and configure

Claude Desktop with the bundle

GSplit is also packed as an MCP Bundle, a file named gsplit-mcp-<version>.mcpb (Windows), available on the download page. In Claude Desktop, double-click the file, or open it from the extensions settings, and confirm. You do not edit any configuration file. The bundle runs server/gsplit-mcp.exe and declares the eight tools below.

Claude Desktop, by hand

Add GSplit to the mcpServers section of claude_desktop_config.json and restart Claude Desktop. Use the full path of the program; double the backslashes on Windows.

Windows

{
  "mcpServers": {
    "gsplit": {
      "command": "C:\\Program Files\\GDG Software\\GSplit\\gsplit-mcp.exe"
    }
  }
}

Linux

{
  "mcpServers": {
    "gsplit": {
      "command": "/usr/bin/gsplit-mcp"
    }
  }
}

Adjust the path to where GSplit is installed. A per-user installation on Windows is in %LOCALAPPDATA%\Programs\GDG Software\GSplit; an all-users installation is in %ProgramFiles%\GDG Software\GSplit. For the portable copy, use the folder you extracted it to.

Claude Code

Windows

claude mcp add gsplit -- "C:\Program Files\GDG Software\GSplit\gsplit-mcp.exe"

Linux

claude mcp add gsplit -- /usr/bin/gsplit-mcp

Other clients

Any MCP client that starts a local server over stdio can use gsplit-mcp: give it the path of the program as the command, with no arguments.

Program options

Option	Meaning
--version	Print the version and exit.
--verbose	Log every request and every engine line to standard error.
--lang <code>	Language of the engine messages. Default: the GSPLIT_LANG environment variable, then the language set in the GSplit Options, then the system language.

Standard output carries nothing but MCP messages. Logs go to standard error, and only with --verbose. The program exits when its input ends.

How it works

• The transport is MCP over stdio: one JSON-RPC 2.0 message per line, in UTF-8.
• Requests are handled one at a time. A tool call runs to the end before the next request is read, so a client cannot cancel it: to stop a split in progress, the client ends the process. The pieces of an unfinished split are deleted, as in every other GSplit front end.
• The server never asks a question. A run that would need an answer (a disk is full, a piece is missing) stops, and the result has isError set to true with the code the console would have returned.
• When the request carries a progress token, split, unite, verify and checksum send progress notifications, from 0 to 100 and at most about four a second, with the name of the piece being read or written. The engine log lines go out as log notifications when the client has set a log level.
• The server tells the agent three things it often gets wrong: paths are absolute, pieceSize is the size of each piece file in bytes, and a text file wants options.recordMode.

Every tool returns its result as JSON text. A refusal by the engine has isError: true and a text holding code, message and data. A call whose arguments break the schema is a JSON-RPC error with code -32602.

Tools

All paths are absolute.

split

Splits a file into pieces.

Parameter	Type	Meaning
source	string, required	The file to split.
dest	string, required	The destination folder, created if needed.
pieceSize	integer, required	Size of each piece file in bytes. Ignored with useOccurrence, recordMode or spanned: send 0.
options	object	Optional settings, below.

The result is the split summary: ok, code, message, totalPieces, totalBytes, companion, manifest, sourceSha256, crcFile, joinScripts, pieceNameMask and renamed. It adds pieces, a list of { number, name, path, size, crc32, sha256 } in piece order (sha256 only when computed), exitCode (what gsplitc would return), and question (the kind of question that stopped the run, when one did). A refusal before the run carries exitCode in its data.

The keys of options, all optional:

Group	Keys
Destination	emptyDestFolder, moveToRecycleBin, overwritePolicy (refuse, overwrite, skip or rename; refuse by default), overwritePieces (older form: true means overwrite), pieceCountTarget
Naming and metadata	pieceNameMask (default disk{num}.gsd), noPieceHeaders, pieceSetID, pieceSetTitle, pieceSetAuthor, pieceSetDesc
Size	firstPieceSizes (list of sizes in bytes), fillFromEnd, pieces (for example 1, 3-5, 37-), reserveFirstPiece, reserveOtherPieces, spanned, bufferSize
Pattern	useOccurrence, occurrencePattern, occurrenceNumber, occurrenceSplitBefore
Text mode	recordMode (none, lines or csv), recordsPerPiece, recordPieceCount, recordMaxBytes, recordSeparatorRegex, recordRegexGroup, recordRegexCutBefore
Header, footer, BOM	insertCustomHeader, customHeader, headerLines, headerOnFirstPiece, insertFooter, footer, insertBOM
Low impact	throttleBytesPerSec, throttlePauseMs
Extra files	writeCrcFile, writeManifest, writeJoinScript, createGUnite, sfu (the Self-Uniting settings)
Check	verifyEachPiece

The values and limits are those of the command line and of the window. For a text file, use recordMode lines or csv with recordsPerPiece, so that no line or record is cut in two.

check_dest

Reports what a destination folder already holds before a split: the planned piece names found there and other files that look like pieces. It creates nothing.

Parameter	Type	Meaning
dest	string, required	The destination folder.
pieceNameMask	string, required	The piece name mask, with {num} or {oru}.
source	string	The file to split; gives {orf}, {ofw} and {ore}.
pieceCount	integer	Number of pieces planned. Missing: from piece 1 while the names exist.
pieces	string	Only these pieces count as existing (1, 3-5, 37-).

inspect

Reads the set a piece belongs to.

Parameter	Type	Meaning
path	string, required	Any piece of the set.

The result describes the set: format, original name and size, the pieces present and the checksum. For a GSplit 4 set it includes the version, the set id, the label and the SHA-256 of the original. For a GSplit set it also holds piece, the metadata of the file you gave (CRC-32, SHA-256, dates in ISO 8601, Unix mode, Windows attributes, creator, text information), or null when that file cannot be read as a GSplit piece. Raw sets and GSplit 1.x sets have no piece key.

verify

Reads every piece and checks the set against its checksums without writing anything.

Parameter	Type	Meaning
firstPiece	string, required	A piece of the set; any piece is accepted.
bufferSize	integer	Buffer in bytes, 1024 to 67108864. Default 65536.

The result is the unite summary of the check.

unite

Rebuilds the original file from its pieces.

Parameter	Type	Meaning
firstPiece	string, required	A piece of the set; any piece is accepted.
dest	string	The output file. Empty or missing: the original name, in the folder of the pieces.
options	object	overwrite (default false), bufferSize, skipBadPieces (default false), restoreMetadata (give the output the original dates and attributes; default true), checksum (a Total Commander .crc file to check a raw set against), verifyOnly.

The result is the unite summary plus output, the file written. Without overwrite, an existing output file is refused with code -32005.

checksum

Computes the CRC-32, MD5 and SHA-256 of a file.

Parameter	Type	Meaning
path	string, required	The file.
bufferSize	integer	Buffer in bytes. Default 1048576.

The result holds crc32, md5, sha256 and size.

presets

Returns the piece-size presets of GSplit as a JSON document: the content of presets.json, or the built-in list. It takes no parameter. See Type and size.

file_info

Gives the size, dates and attributes of a file, with its text detection.

Parameter	Type	Meaning
path	string, required	The file.

The text detection adds isText, encoding, lineEnding, bomBytes, sampleBytes and sampleLines. The type label and the icon are empty: they come from the Windows shell, which the console does not use. Call file_info first to know whether a file is text.

Examples

You do not write these calls: the assistant does. You can ask it in plain words.

• "Split D:\video\film.mkv into 700 MB pieces in E:\pieces and write a SHA-256 manifest." The assistant calls check_dest, then split with pieceSize 734003200 and writeManifest set to true.
• "Is the set that starts at E:\pieces\disk1.gsd complete and undamaged?" It calls inspect, then verify.
• "Split this CSV export into files of 50 000 records." It calls file_info, then split with recordMode csv and recordsPerPiece 50000.
• "Put the file back together in D:\restored." It calls unite with dest set to the output file.

Safety

Caution

gsplit-mcp runs with your user rights and can read and write any file you can. The agent chooses the paths. Keep your client's approval prompts on for tool calls, and read the paths before you allow a call.

• split with emptyDestFolder empties the destination folder first. On Windows the content goes to the Recycle Bin by default (moveToRecycleBin); on Linux it is deleted. GSplit refuses to empty a folder that contains the source.
• split and unite refuse to replace existing files unless the agent sets overwritePolicy to overwrite, or overwrite to true.
• The server never asks you anything. A run that needs a decision stops with an error and writes nothing more.
• verify, inspect, checksum, check_dest, presets and file_info do not change any file.
• Pieces and outputs are written under a temporary .gspart name and renamed once complete, so a killed run does not leave a half-written file under its final name.

Error codes

A tool call that fails returns one of these codes, also used by the JSON-RPC interface of GSplit.

Code	Meaning
-32000	Engine error, or a split is already running.
-32001	Source file not readable.
-32002	Destination not writable.
-32003	Piece size invalid, or not enough space.
-32004	Stopped by the user.
-32005	Pieces already exist.
-32006	Occurrence pattern not found.
-32007	A piece was not written completely.
-32008	A piece failed verification.
-32009	The source changed during the split.
-32010	Piece set not recognised, or first piece unreadable.
-32011	A piece is missing.
-32012	A piece belongs to another set or has the wrong number.
-32013	A piece failed the running CRC check.
-32014	A piece is shorter than announced.
-32015	The united file does not match the original (kept).
-32016	A piece could not be read while copied.
-32602	Invalid parameters.

See also

• Command line: GSplit and gsplitc
• Command line: gunitec
• Installation
• Type and size