HISTORICAL, AS OF v4.0.0 (2026-09-11). Do not follow the commands in this guide.
Every tool it tells you to run was removed in v4.0.0:
cyberchef_migration_preview,cyberchef_deprecation_stats, thecyberchef-migratebinary, and thecompatibility.suppressDeprecations/compatibility.v2CompatibilityModesettings. Following this document today yields commands that fail and a config file the server refuses to start on.There is nothing left to migrate. v2.0.0 shipped in August 2026 and its formats have been the only formats since. Recipes in every v1 shape still bake unchanged — positional arguments, bare string operations and named-object arguments all produce identical output, which is why the migration tooling was retired rather than maintained.
The document is kept because DEP001/DEP007/DEP008 record a withdrawn breaking change — the
cyberchef_prefix was announced for removal and the decision was reversed on measurement — and that reversal is still load-bearing: the prefix is permanent. Seedocs/releases/v4.0.0.md.
This document describes all breaking changes planned for CyberChef MCP v2.0.0 and provides migration guidance for users upgrading from v1.x.
- Overview
- Breaking Changes Summary
- Withdrawn Changes (DEP001, DEP007, DEP008)
- Recipe Schema Format (DEP002)
- Error Response Format (DEP003)
- Configuration System (DEP004)
- Legacy Argument Handling (DEP005)
- Recipe Array Format (DEP006)
- (Meta-tool renames DEP007/DEP008 — withdrawn, see item 3)
- MCP Protocol Version Updates
- Migration Examples
- Testing Your Migration
- FAQ
CyberChef MCP v2.0.0 introduces several breaking changes to improve consistency, maintainability, and alignment with MCP best practices. These changes were announced in v1.8.0 with deprecation warnings to give users time to prepare.
| Version | Status | Description |
|---|---|---|
| v1.8.0 | Released | Deprecation warnings introduced |
| v1.8.x | Current | Migration preview tools available |
| v2.0.0 | Planned | Breaking changes enforced |
- Enable deprecation warnings (default in v1.8.0+)
- Use the migration preview tool to analyze your recipes
- Test with v2 compatibility mode:
V2_COMPATIBILITY_MODE=true - Update your code following this guide
| Code | Feature | Impact | Migration Effort |
|---|---|---|---|
| DEP001 | Tool naming convention | WITHDRAWN — nothing to do | None |
| DEP002 | Recipe schema format | Recipe definitions | Medium |
| DEP003 | Error response format | Error handling | Low |
| DEP004 | Configuration system | Server configuration | Low |
| DEP005 | Legacy argument handling | Recipe arguments | Medium |
| DEP006 | Recipe array format | Recipe structure | Medium |
| DEP007 | cyberchef_bake rename | WITHDRAWN — nothing to do | None |
| DEP008 | cyberchef_search rename | WITHDRAWN — nothing to do | None |
Three of the eight announced changes are not happening. DEP001, DEP007 and DEP008 warned since v1.8.0 that the
cyberchef_prefix would be removed. It is not being removed, in v2.0.0 or later. See Withdrawn Changes for the measurements behind the reversal. If you already renamed your tool calls in anticipation, revert them — the prefixed names are the ones that work.
These three deprecations are withdrawn, not deferred. No release will remove the cyberchef_
prefix, and cyberchef_bake and cyberchef_search keep their names.
{
"method": "tools/call",
"params": {
"name": "cyberchef_to_base64",
"arguments": { "input": "Hello World" }
}
}That is correct in v1.x and it is correct in v2.0.0. No migration is required. If you renamed tool calls in anticipation of the announced change, revert them.
This is a reversal of a promise published in v1.8.0, so the reasoning is set out rather than the change simply dropped. All three points were measured against the running server:
1. It saves 2.6%. The tools/list payload is 483 tools, 183,115 bytes, roughly 45,800 tokens —
charged on every request before the user types anything. Removing the prefix from every name saves
1,208 bytes. That is rounding error against the real number, and it does not justify breaking
every existing integration.
2. Nineteen names collide once bare. MCP keeps tool names in a flat namespace per session, so a bare name competes with every other connected server:
bake search md5 sha1 sha2 hash filter sort merge diff
reverse unique fork jump label comment register subtract parse_uri
Nearly every other MCP server plausibly defines search. The prefix is what makes exposing a tool
called "search" safe at all — which makes DEP007 and DEP008 the worst two of the three to enact.
3. The real problem is the tool count, not the name length. Published measurement puts model
tool-selection quality as degrading past roughly 50 tool definitions; this server exposes 483.
Curating which tools are exposed by default is a ~90% context reduction with no loss of reach,
because cyberchef_bake can invoke any operation by name and cyberchef_search discovers them.
Shortening names is a 2.6% reduction that breaks callers. The effort went to the first.
No code can depend on a name that has never shipped. The prefixed names have worked in every release and continue to.
emitDeprecation("DEP001") no longer emits a deprecation. It emits a one-time informational
notice, and — importantly — it is not elevated to an error under V2_COMPATIBILITY_MODE:
[WITHDRAWN] DEP001: Tool naming convention -- the announced change is NOT happening.
WITHDRAWN: the 'cyberchef_' prefix is NOT being removed. It stays permanently.
No action required. Keep using cyberchef_to_base64 and the other prefixed names.
V2_COMPATIBILITY_MODE=true exists so you can find out what v2.0.0 will break. Reporting a
withdrawn change as an error there would be actively misleading — telling you to migrate away from
a name that is staying is worse than saying nothing.
getToolName() returns the prefixed name in every mode, including with an explicit
forV2 = true. The parameter is retained because it is exported and callers pass it; changing the
arity would be a breaking change in service of a no-op.
Recipe validation will use enhanced Zod v4 schemas with stricter type checking.
Loose validation allowing various formats:
{
"recipe": [
{ "op": "To Base64" }
]
}Strict validation requiring complete recipe objects:
{
"recipe": {
"name": "My Recipe",
"description": "Optional description",
"operations": [
{ "op": "To Base64", "args": {} }
]
}
}- Wrap array recipes in object format with
nameandoperations - Add explicit
argsobjects to all operations (even if empty) - Use the
cyberchef_migration_previewtool to validate recipes
Error responses will include structured error codes for programmatic handling.
{
"error": {
"message": "Invalid input: expected string"
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid input: expected string",
"details": {
"expected": "string",
"received": "number",
"path": "arguments.input"
}
}
}| Code | Description |
|---|---|
INVALID_INPUT |
Input validation failed |
OPERATION_NOT_FOUND |
Unknown operation name |
OPERATION_FAILED |
Operation execution error |
RECIPE_INVALID |
Recipe validation failed |
RATE_LIMITED |
Request rate limit exceeded |
QUOTA_EXCEEDED |
Resource quota exceeded |
INTERNAL_ERROR |
Unexpected server error |
- Update error handling to use error codes
- Add fallback handling for the
messagefield - Log or display
detailswhen available
Corrected in v2.10.0. This section previously described the file below as shipping in v2.0.0. It did not: no loader was written, and a
cyberchef.config.jsonwas read by nothing at all until v2.10.0. If you created one on the strength of this guide between v2.0.0 and v2.9.0, it was silently ignored, and it will start taking effect the moment you upgrade to v2.10.0 -- check its contents before you do. The schema below is the one that actually exists.
Settings can be given in a cyberchef.config.json file as well as through environment variables.
Nothing is required: a deployment with no file behaves exactly as it did before.
Sections group the settings; every setting is also still an environment variable. Written to the
working directory, or wherever CYBERCHEF_CONFIG_FILE points.
{
"server": { "maxInputSize": 10485760, "operationTimeout": 30000 },
"cache": { "enabled": true, "maxSize": 104857600 },
"security": { "offline": false, "maxRegexLength": 1000 },
"tools": { "surface": "index" },
"observability": { "metricsEnabled": false, "telemetryEnabled": false }
}The available sections are server, cache, batch, streaming, workers, retry,
rateLimit, recipes, http, socket, auth, tools, security, observability
and compatibility. Every setting name and its environment-variable equivalent is listed in
the configuration guide.
environment variable > config file > built-in default
So docker run -e CYBERCHEF_OFFLINE=true still wins over a file baked into the image. The startup
log names any setting the environment overrode, so the two never disagree silently.
Malformed JSON, an unknown section, an unknown setting or a value of the wrong type stops the server, with a message naming the mistake:
cyberchef.config.json: unknown setting "security.offlien" (did you mean "offline"?).
Known settings in "security": auditEnabled, maxRegexLength, offline
The server did not start. Fix the file, or remove it to use environment variables only.
That is deliberate. This file sets the offline switch, the regex-length cap and the operation allowlist, and the defect being corrected here was a configuration that was accepted and ignored. Running on defaults an operator did not choose, and does not know they have, is the worse outcome.
- Create
cyberchef.config.jsonin the working directory, or pointCYBERCHEF_CONFIG_FILEat one. - Move settings out of environment variables into it, using the section names above.
- Keep environment variables for whatever should be deployment-specific -- they win.
- Start the server and read the
Config file:line in the startup log to confirm what applied.
Positional array arguments will be replaced with named object arguments.
{
"op": "To Base64",
"args": ["A-Za-z0-9+/=", true]
}{
"op": "To Base64",
"args": {
"alphabet": "A-Za-z0-9+/=",
"showPrefix": true
}
}- Convert array arguments to named objects
- Use the
cyberchef_migration_previewtool in "transform" mode - Consult operation documentation for argument names
| Index | Name | Type |
|---|---|---|
| 0 | alphabet |
string |
| Index | Name | Type |
|---|---|---|
| 0 | key |
string |
| 1 | iv |
string |
| 2 | mode |
string |
| 3 | inputType |
string |
| 4 | outputType |
string |
| Index | Name | Type |
|---|---|---|
| 0 | find |
string |
| 1 | replace |
string |
| 2 | global |
boolean |
Recipe operations using simple arrays will require explicit operation objects.
[
{ "op": "To Base64", "args": [] },
{ "op": "MD5", "args": [] }
]{
"name": "Encode and Hash",
"operations": [
{ "op": "To Base64", "args": {} },
{ "op": "MD5", "args": {} }
]
}- Wrap array recipes in an object with
nameandoperations - Convert array
argsto objectargs - Add optional
descriptionandmetadatafields
Withdrawn. cyberchef_bake and cyberchef_search keep their names permanently. See
Withdrawn Changes.
CyberChef MCP v2.0.0 will require MCP protocol version 2024-11-05 or later.
- Streaming responses - Large outputs will use streaming
- Progress notifications - Long operations report progress
- Cancellation support - Operations can be cancelled mid-execution
- Resource management - Explicit resource lifecycle management
Ensure your MCP client supports:
- Protocol version
2024-11-05or later - Streaming content handling
- Progress notification handling
Tool names do not change. This is correct in v1.x and in v2.0.0:
const result = await client.callTool({
name: "cyberchef_to_base64",
arguments: { input: "Hello World" }
});An earlier draft of this guide showed an "After" block renaming this to to_base64. That was the
DEP001 rename, which is withdrawn — the server has never
exposed to_base64 and never will, so following that example would have produced a
Tool not found error. Keep the prefixed name.
The tool name is unchanged — cyberchef_bake in both. What changes is the recipe shape
(DEP006) and the argument shape (DEP005).
Before (v1.x):
{
"method": "tools/call",
"params": {
"name": "cyberchef_bake",
"arguments": {
"input": "Hello World",
"recipe": [
{ "op": "To Base64", "args": ["A-Za-z0-9+/="] },
{ "op": "MD5", "args": [] }
]
}
}
}After (v2.0.0):
{
"method": "tools/call",
"params": {
"name": "cyberchef_bake",
"arguments": {
"input": "Hello World",
"recipe": {
"name": "Encode and Hash",
"operations": [
{ "op": "To Base64", "args": { "alphabet": "A-Za-z0-9+/=" } },
{ "op": "MD5", "args": {} }
]
}
}
}
}Before (v1.x):
try {
const result = await client.callTool(params);
} catch (error) {
console.error("Error:", error.message);
}After (v2.0.0):
try {
const result = await client.callTool(params);
} catch (error) {
console.error(`Error [${error.code}]: ${error.message}`);
if (error.details) {
console.error("Details:", JSON.stringify(error.details, null, 2));
}
}{
"method": "tools/call",
"params": {
"name": "cyberchef_migration_preview",
"arguments": {
"recipe": [
{ "op": "To Base64", "args": ["A-Za-z0-9+/="] }
],
"mode": "analyze"
}
}
}Response:
{
"compatible": true,
"issues": [
{
"code": "DEP005",
"location": "operations[0].args",
"message": "Positional array arguments are deprecated",
"severity": "warning",
"fix": "Convert array arguments to named object: { key: value }"
},
{
"code": "DEP006",
"location": "root",
"message": "Recipe passed as array instead of object",
"severity": "warning",
"fix": "Wrap recipe in object: { name: 'Recipe Name', operations: [...] }"
}
],
"issueCount": 2,
"breakingCount": 0,
"warningCount": 2
}Deprecation warnings are enabled by default in v1.8.0+. To ensure they're active:
# Ensure warnings are NOT suppressed
unset CYBERCHEF_SUPPRESS_DEPRECATIONSAnalyze your recipes for compatibility:
{
"method": "tools/call",
"params": {
"name": "cyberchef_migration_preview",
"arguments": {
"recipe": { /* your recipe */ },
"mode": "analyze"
}
}
}Test with v2.0.0 behavior (deprecations become errors):
V2_COMPATIBILITY_MODE=true npm run mcpOr in Docker:
docker run -i --rm -e V2_COMPATIBILITY_MODE=true cyberchef-mcpUse the transform mode to automatically convert recipes:
{
"method": "tools/call",
"params": {
"name": "cyberchef_migration_preview",
"arguments": {
"recipe": [ /* legacy recipe */ ],
"mode": "transform"
}
}
}Review which deprecations you've triggered:
{
"method": "tools/call",
"params": {
"name": "cyberchef_deprecation_stats",
"arguments": {}
}
}A: v2.0.0 is planned for release after sufficient time has been given for users to migrate. Monitor the changelog and release notes for updates.
A: Yes, set CYBERCHEF_SUPPRESS_DEPRECATIONS=true. However, this is not recommended as it may cause issues when upgrading to v2.0.0.
A: No, v2.0.0 will enforce the new formats. Use the migration preview tool to update your recipes before upgrading.
A: Open an issue on the GitHub repository with:
- Your current version
- The deprecation code(s) involved
- Your original recipe/configuration
- The error or unexpected behavior
A: The transformRecipeToV2 function (available via the migration preview tool) provides automatic transformation. However, the result should be reviewed as some transformations are best-effort (e.g., array arguments are converted to arg0, arg1, etc.).
A: You can continue using v1.8.x until you're ready to migrate. v1.8.x will receive security updates for a reasonable period after v2.0.0 release.
A: Ensure your MCP client supports protocol version 2024-11-05 or later. Most modern MCP clients are compatible.
A: Use the cyberchef_search tool to get operation details, or consult the CyberChef documentation. Argument names follow the operation's parameter names.
- Documentation: Project README
- Issues: GitHub Issues
- Discussions: GitHub Discussions
This document is part of CyberChef MCP v1.8.0 - Breaking Changes Preparation release.