mcp-z-cli

@mcp-z/cli

Use a project's existing MCP configuration from a shell-capable agent, without writing a connection script. When the project selects CLI access, keep its calls on that route rather than substituting native agent MCP tools.

Run and locate configuration

Requires Node.js 20 or newer. For one-shot use:

npx -y @mcp-z/cli inspect --servers SERVER --tools

Alternatively, install with npm install -g @mcp-z/cli and use mcp-z or its alias z. The examples below use mcp-z; the remaining arguments are identical with either executable or the npx prefix. SERVER and TOOL are placeholders for discovered names, not built-in aliases.

With no --config, commands find the nearest .mcp.json from the current working directory upward, through the home directory inclusive. Outside the home directory tree, lookup checks only the current directory. Run from the intended project or its subdirectory; a nearer config takes precedence over a parent's. Configured child processes start with the config directory as their working directory.

Let that lookup select the project's ordinary .mcp.json; examples omit --config for this reason. Use --config when the task selects another configuration or needs an exact path: a bare filename such as .mcp.staging.json searches upward; ./.mcp.staging.json or an absolute path selects that exact file. Server names are keys under mcpServers. Inspect the relevant entry without exposing its credentials.

Discover as the task requires

Start with the task's existing evidence, such as a document link in local project notes, and load enough context to resolve the next uncertainty. Configuration membership alone does not make a server relevant. When the server is known, inspect it directly. When the capability is unfamiliar, search likely servers first and expand when the results are insufficient. For example, finding an unfamiliar spreadsheet operation starts with a short candidate list:

mcp-z search "spreadsheet" --servers sheets --types tool --limit 5

Here sheets is an illustrative configured server name. After choosing a candidate, inspect its server's schema, saving and selecting locally when the server exposes many tools. The schema extraction example shows that path. A small server's schema output can simply be read directly:

mcp-z inspect --servers SERVER --tools --json

Discovery returns live server-owned names and schemas; use those rather than guessing parameters from a tool's name. Search is unnecessary when the desired tool and its applicable schema are already known. A schema does not need fetching again for every call. Search results may be limited or incomplete if a server failed to connect, particularly in JSON mode where connection warnings are suppressed. Inspect the expected server before concluding a capability is absent.

Readable output is the default. Search descriptions are shortened; ordinary inspect output does not include full input schemas. Use inspect --tools --json for complete schemas, or --verbose for readable parameter details. JSON is useful for parsing and saving results, but is not inherently smaller. Request bounded data where the tool supports it; for large responses, save the full output and inspect relevant portions locally. Small results may be cheaper to read whole. Preserve errors, continuation tokens, and evidence of completeness when filtering.

Call and check the result

mcp-z call-tool SERVER TOOL '{"argument":"value"}' --json

Replace the illustrative JSON with the tool's actual input object; use '{}' when it needs no arguments. These inline examples use POSIX shell quoting. JSON must reach the CLI as one argument; shell-specific alternatives are in saved output and argument handling.

Discovery does not authorize a write. Tool calls stay within the user's requested action. Check command failure and the returned data: successful application payloads can still report per-item failures. call-tool --json prints the parsed tool result rather than a guaranteed raw MCP envelope. After an uncertain write outcome, read the target before retrying because the write may already have succeeded.

Task examples

These are independent examples, not a reading sequence. Their descriptions identify when they are relevant; the main workflow may already provide everything needed. A prompt/resource reference becomes useful when that capability is part of the task, not to establish that an ordinary tool call does not need it.

• For a real provider read or an authorized bounded update, use read and update a spreadsheet. It also explains operation-triggered OAuth for MCP-Z Google and Microsoft servers.
• For large results, schema extraction, or shell argument handling, use saved output and argument handling.
• When a discovered prompt or resource fits the task, use prompts and resources.
• When working without a config, attaching to HTTP servers, or diagnosing protocol negotiation, use connection options.

Use mcp-z --help or mcp-z COMMAND --help for the installed command's options. Capability discovery through the CLI avoids preloading every schema into model context; it does not imply that every configured server process is started lazily.