Skip to content

Call, prompt, and read

mcpdev call, prompt, and read exercise one advertised primitive on a stdio child or Streamable HTTP endpoint. You do not route the request through an AI host. Connection flags are the same as Inspect a server. The command contract is in CLI.

Application-level tool failures (isError: true) are a successful RPC. Transport and JSON-RPC failures stay on exit classes 10 and 20.

Tool call

JSON arguments default to {}. Load an object from inline text, a file, or stdin. Repeatable --arg KEY=JSON merges on top (later keys win). Invalid JSON is usage (exit 2).

mcpdev --command ./bin/weather call echo --args '{"text":"hi"}'
mcpdev --command ./bin/weather call echo --args-file ./args.json
mcpdev --command ./bin/weather call echo --args - < ./args.json
mcpdev --command ./bin/weather call echo --arg text='"hi"'

--fail-on-tool-error maps server isError to assertion exit 30. Without it, stdout still includes isError: true and the process exits 0.

A missing tools capability, or a JSON-RPC error from the server, is protocol exit 20. It is not an empty successful result.

Prompt get

Prompt arguments are strings. --arg name=true sends the string true. A --args object may only contain strings; numbers and booleans are usage errors so a flag is not silently JSON-coerced.

mcpdev --command ./bin/weather prompt greet --arg name=true
mcpdev --format json --url http://127.0.0.1:8080/mcp prompt greet --args '{"name":"lab"}'

Resource read and templates

read URI calls resources/read. --template expands RFC 6570 {var} (percent-encode) and {+var} (reserved) using the same string --arg / --args rules as prompts. Unexpanded or unknown operators are usage errors.

mcpdev --command ./bin/weather read fixture://stable/note
mcpdev --command ./bin/weather read --template 'fixture://items/{id}' --arg 'id=a b'

The expanded URI for id=a b is fixture://items/a%20b.

Output, binary, and size

Human mode prints text. Image, audio, and blob parts are labeled with MIME type and byte length. They are never dumped as raw bytes on stdout.

--format json keeps kind on every content block. Binary is data_base64 or blob_base64. --save PATH writes the full body (including binary) to a file you named; stdout still follows the size bound.

--max-bytes (default 65536) truncates stdout text and omits oversized binary from stdout (truncated: true). The saved file is not truncated.

mcpdev --format json --command ./bin/weather read fixture://stable/blob --save ./out.bin --max-bytes 1

--timeout bounds the RPC. Interrupt cancels the context. Connect failures stay class 10.

Do not pass server-returned URIs or names to a shell. --save is a local path you supply, not a server string.