CLI
This document lists every mcpeak command with its flags and defaults. To run through one end to end first, see quick start.
mcpeak <command> [options]
mcpeak help [command]mcpeak --help, -h, and help print the full help text. Running with no arguments does the same, writing it to stdout and exiting with code 0. mcpeak help test and mcpeak test --help are equivalent. --version prints the version.
Three ways to specify a server
test, generate, optimize, and audit accept the same three forms. Use only one.
| Form | Meaning |
|---|---|
-- <executable> [args...] | Everything after -- is the command that starts the server. The first token is the executable, the rest are arguments. Nothing after that is parsed further |
--command <executable> [--arg <value> ...] | The same thing as flags. Repeat --arg as needed. A value starting with a hyphen goes as --arg=-m, and an empty value as --arg= |
--url <URL> | Attaches to an already running Streamable HTTP server. Since no process is started, stdio-only options are not accepted |
--env <NAME> is available for stdio, and --header-env <header>=<env var> for HTTP.
| Option | Meaning |
|---|---|
--env <NAME> | Passes the parent environment variable NAME to the server process. Can be repeated. The SDK only gives the child a fixed list such as HOME and PATH, so any value the server reads from the environment, such as an API key, needs to be named explicitly here. Names starting with NODE_OPTIONS or MCPEAK_ are used by the record and replay wiring and are not accepted |
--header-env <header>=<env var> | Reads a request header value from an environment variable and attaches it |
Neither option accepts the value directly, since a token written on the command line stays in the ps list and shell history. Set the value without putting it in history either.
read -rs MCP_TOKEN; export MCP_TOKEN
mcpeak test suite.json --url http://127.0.0.1:3000/mcp --header-env Authorization=MCP_TOKENtest
mcpeak test <suite.json> <server target>
[--determinism] [--reset-cmd <command>]
[--json] [--junit <path>] [--repair-bundle <path>] [--stderr-lines <N>]
[--session <path> | --record-session <path>]Starts the server from the JSON suite and validates it. Exits 0 if every case passes, and 1 if there is a failure, timeout, or abort, or an input, connection, or exit error. Only the report goes to stdout; CLI errors and server diagnostics go to stderr.
| Option | Default | Meaning |
|---|---|---|
--determinism | off | Runs the suite twice and compares the results. This is a non blocking diagnostic, so finding a difference does not change the exit code. See determinism check |
--reset-cmd <command> | none | Runs this command once before each run. It does not go through a shell, so pipes and && cannot be used |
--json | off | Writes RunnerReport JSON to stdout instead of the human readable report |
--junit <path> | none | Writes JUnit XML to that path. If it cannot be written, exits 1 with JUNIT_WRITE_FAILED even if every case passed |
--repair-bundle <path> | none | Writes a bundle containing only the failed cases. See Repair |
--stderr-lines <N> | 20 | The number of lines in the server diagnostics block attached to stderr on failure. 0 turns the block off |
--record-session <path> | none | Records the HTTP calls the server makes outward through globalThis.fetch |
--session <path> | none | Replays recorded external calls |
The two session options cannot be used together, or together with --determinism. Their scope and what they store are covered in External session.
The fingerprint line at the end of the report states whether the suite approved by generate matches the current file. It does not change the verdict. In --json it is always present under the spec key.
generate
mcpeak generate --out <suite.json> <server target>
[--suite-id <id>] [--name <name>]
[--baseline-only] [--provider <codex|claude>] [--model <model>]
[--no-dry-run] [--reset-cmd <command>] [--fixtures <path>]
[--no-repair] [--diagnose-rejections] [--force]Builds a suite from the server's tool schemas. The flow is described in generating a suite.
| Option | Default | Meaning |
|---|---|---|
--out <suite.json> | required | The path to save to. The file name is included in the approval fingerprint |
--suite-id <id> | derived from the file name | For contract.suite.json this is contract |
--name <name> | same as --suite-id | The name printed on the first line of the report |
--baseline-only | off | Non interactive approval that does not call an AI. Also skips the dry run |
--provider <codex|claude> | selected in a TTY | The CLI to use for AI review |
--model <model> | selected in a TTY | The model to pass to the provider |
--no-dry-run | off | Skips the dry run before approval. This also skips any AI pre-fill that requires a run |
--reset-cmd <command> | none | Runs once before the dry run |
--fixtures <path> | mcpeak.fixtures.json | JSON listing values that point to real resources, per tool and field. If absent, generation proceeds without it |
--no-repair | off | Does not fix input values and retry when the dry run fails |
--diagnose-rejections | off | Lists the responses of passing rejection cases and, if a provider is set, asks it for a reference opinion |
--force | off | Deletes and rewrites the file at --out if one already exists. By default, saving stops instead |
repair
mcpeak repair <bundle.json> --provider <codex|claude> --model <model>
[--max-cases <N>] [--no-stderr] [--yes]Uses a bundle produced by test --repair-bundle to get suggested cause candidates in the server code. The flow is described in Repair.
| Option | Default | Meaning |
|---|---|---|
--provider <id> | required | codex or claude |
--model <model> | required | The model identifier to pass to the provider |
--max-cases <N> | all | The maximum number of failures to send at once. Excess cases are dropped from the end, keeping the first ones |
--no-stderr | off | Excludes server stderr from what is sent |
--yes | off | Skips the confirmation screen before sending |
optimize
mcpeak optimize --out <overlay.json> <server spec> [--json]Reads the server's tools/list and builds an overlay that shrinks the definitions without changing their meaning. The report goes to stdout. The flow and the list of transformations are described in Optimize.
| Option | Default | Meaning |
|---|---|---|
--out <overlay.json> | required | Where to write the overlay. An existing file is overwritten, because you rebuild it with the same command whenever the server changes |
--json | off | Prints the overlay JSON to stdout instead of the report |
The overlay is served with mcpeak-optimize-proxy. Only tools/list changes; tool names, arguments, and call results are the same as the origin. Common parameter descriptions are moved into the server instructions, so in a client that does not show instructions to the model, those descriptions never reach the model.
audit
mcpeak audit <server spec>
[--probe readonly|none|all] [--baseline <path>] [--update-baseline]
[--sandbox [--sandbox-session <path> | --sandbox-replay <path>]
[--allow-host <host> ...] [--compare-host] [--sandbox-mount <dir>]]
[--json]Checks a server's tool definitions and protocol for security risks before you use it. Exits with 2 when there is a critical or warning finding, 0 when there is none, and 1 on a connection or input failure. Permission combination warnings and informational findings do not affect the exit code. The check families and how to read the result are described in Audit.
| Option | Default | Meaning |
|---|---|---|
--probe <policy> | readonly | How far to actually call tools. readonly calls only tools whose readOnlyHint is true, none calls nothing and skips response checks, all calls every tool, so use it only in a disposable environment. A run where --sandbox isolation is actually on defaults to all |
--baseline <path> | none | The baseline file for tool definitions. Created if missing; otherwise compared against the current definitions and changed tools are reported |
--update-baseline | off | Rewrites the baseline file with the current definitions without comparing. Must be used with --baseline |
--json | off | Prints the result JSON to stdout instead of the report. For the same server and the same command it is identical down to the byte |
--sandbox | off | Starts the server inside a Docker container and calls every tool to observe file, process, and network behavior. Only servers launched with node, npx, or npm are isolated; if isolation cannot start, the server runs on this machine without it and the second line of the report says so. Cannot be used with --url |
--sandbox-session <path> | none | Records the HTTP round trips the sandboxed server makes into this file |
--sandbox-replay <path> | none | Answers only from this session file, without contacting upstream. Cannot be used with --sandbox-session |
--allow-host <host> | none | Adds to the declared destinations. Repeatable. Connections to that host and its subdomains are treated as declared by the server |
--compare-host | off | Starts the server once more on this machine without isolation, fetches only tools/list, and compares it with the tool surface seen inside the sandbox. No tools are called, but the server's startup code runs on this machine |
--sandbox-mount <dir> | the directory of the nearest pnpm-workspace.yaml or .git | The host directory made visible read only inside the container. The home directory and / are not allowed |
When launching a stdio server, common secret names such as GITHUB_TOKEN are filled with fake values (canaries). Names passed with --env receive the real value instead. No value is written to the output.
perf
mcpeak perf <suite.json> (-- <executable> [args...] | --command <executable> [--arg <value> ...] [--env <NAME> ...])
[--repeat <n>] [--interval-ms <ms>] [--tool <name> ...]
[--baseline <path> [--update-baseline]] [--threshold-pct <n>] [--threshold-ms <n>] [--json]Calls each callTool case in the suite that does not expect a rejection (isError: true) repeatedly, and prints to stdout a table that splits the response time into external HTTP wait (from the start of each request to the end of its response body) and in-server time. It diagnoses sequential independent requests and repeated requests, but diagnostics do not change the exit code. Exits with 0 when the measurement finishes, 2 on a baseline regression, and 1 on a usage error, connection failure, suite error, or baseline file error. Progress lines go to stderr. The diagnostic rules and how to read the report are described in @mcpeak/perf.
The server can only be specified with -- or --command; --url and --header-env are rejected. The observation code has to be loaded into the server process, so a remote server this tool did not start cannot be measured. Servers that are not Node only get response time and cold start.
| Option | Default | Meaning |
|---|---|---|
--repeat <n> | 5 | Calls per case. An integer from 1 to 100 |
--interval-ms <ms> | 0 | Wait between calls. An integer from 0 to 60000. At 0, a server's rate limiter wait may show up as in-server time |
--tool <name> | none | Measures only the cases for that tool. Repeatable |
--baseline <path> | none | Compares with the baseline file. In-server p50 above the allowance, or more external requests per call, is a regression and exits with 2 |
--update-baseline | off | Writes the baseline file from this measurement without comparing. Must be used with --baseline and cannot be combined with --tool (the baseline is always rewritten from the whole suite) |
--threshold-pct <n> | 50 | The ratio in the in-server allowance baseline × (1 + n/100) + threshold-ms. An integer from 0 to 1000 |
--threshold-ms <n> | 20 | The floor of the same allowance. An integer from 0 to 60000 |
--json | off | Prints the result JSON to stdout instead of the report |
External wait swings widely with the network, so it is shown but left out of the baseline verdict. Giving --baseline to a run where no external calls could be observed prints the report and then exits with 1. Options only test has (--junit, --repair-bundle, --determinism, --reset-cmd, --stderr-lines, --session, --record-session) are not accepted.
Separate executables
| Command | Package | Meaning |
|---|---|---|
mcpeak-mock <definition.json> | @mcpeak/mock | Starts a stdio mock server from a definition file. See mock server |
mcpeak-optimize-proxy <overlay.json> (-- <server command> | --url <URL>) | @mcpeak/optimize | A stdio proxy that serves the overlay and forwards tools/call to the origin server. See Optimize |
mcpeak-dashboard [--port <number>] | @mcpeak/dashboard | The local web UI. Default port 7357, or automatic if 0 is given. See dashboard |
A global install only places that package's own executable, so install all four separately.
Error codes
If the run itself fails, stderr gets an 오류 [<코드>]: <메시지> line along with a 해결: line. Connection errors take the form MCP_CONNECTION_FAILED/<detail code>.
| Detail code | Meaning |
|---|---|
PROCESS_START_FAILED | The server process could not be started. Check the command and cwd |
HANDSHAKE_TIMEOUT / HANDSHAKE_FAILED | The process started, but the MCP handshake did not finish |
PROCESS_EXITED | The server exited before the handshake or during the run. The diagnostics block carries the exit code and stderr |
HTTP_CONNECT_FAILED / HTTP_UNAUTHORIZED / HTTP_STATUS_ERROR | Could not connect to the --url target |
HTTP_SESSION_LOST | The HTTP session was lost during the run |
Codes for a malformed suite file are listed under validation errors in the suite spec.
Supported scope
Supports a single UTF-8 JSON suite and stdio or Streamable HTTP servers. Shell syntax, multiple suites, and TypeScript module suites are not accepted. On Windows, .cmd and .bat are not accepted as the command. Give an executable the operating system can run directly, and pass a script path as an argument.