The client command provides a containerized client convenience wrapper for tool discovery, invocation, and debugging. Use the following patterns to list tools, view details, and invoke operations using the mcpgen client command.
Action Command
List tools with descriptions ./mcpgen client <profile_name>
Show full tool details ./mcpgen client <profile_name> --list-details
Show details for a specific tool ./mcpgen client <profile_name> --list-details --tool getInventoryRecords
Invoke a tool ./mcpgen client <profile_name> --tool listProducts --args '{"limit":3}'
Invoke a tool with pretty JSON args through a file ./mcpgen client <profile_name> --tool getOrders --args @args.json
Invoke a tool with args from file (explicit flag) ./mcpgen client <profile_name> --tool getOrders --args-file args.json
List tools in JSON format ./mcpgen client <profile_name> --list-json
Raw tool output (no automatic JSON parse) Append --raw (if implemented)
Debug HTTP requests/responses Append --debug to see detailed HTTP communication

Options for the client Command

Use the following table to understand the purpose of each option and see examples of how to use them with the client command:
Option Purpose Example
--tool NAME Invoke a specific tool by name, or filter tools --tool listProducts
--args JSON Provide tool arguments as a JSON string or file --args '{"limit":3}' or --args @args.json
--args-file PATH Read tool arguments from a JSON file --args-file args.json
--sa-token Use a specific service account token by name --sa-token admin
--raw Output raw tool response without JSON formatting For parsing in scripts
--list-json Output tools with names and descriptions in JSON For programmatic use
--json Suppress all non-JSON informational output; stdout contains only valid JSON For use with automation and CI pipelines; safe to pipe the output to JSON parser such as jq
--list-details Show full tool details including schema and examples For API exploration; combine with --tool
--debug Display detailed HTTP request and response info For troubleshooting HTTP issues

Examples

  • When you run ./mcpgen client <profile> without specifying a tool, the following output is displayed:
    🛠️  Tools: 12 | 📝 Prompts: 2
ToolNames:
- getInventoryRecords: Retrieve standard inventory stock levels and availability
- getShippingRecords: Retrieve order fulfillment and delivery tracking records
- getSupportTickets: Retrieve customer service tickets and issue tracking records
...

    Each tool is shown with its name and description to help you understand what it does.

  • When you run ./mcpgen client <profile> --list-details, the output displays beautified metadata for each tool:
    • To show all tools:
      ./mcpgen client <profile_name> --list-details
    • To show only a specific tool:
      ./mcpgen client <profile_name> --list-details --tool getInventoryRecords
    The following output displays:
    🛠️  Tools: 13 | 📝 Prompts: 2

================================================================================
📋 TOOL DETAILS
================================================================================

────────────────────────────────────────────────────────────────────────────────
🔧 Tool #1: getInventoryRecords
────────────────────────────────────────────────────────────────────────────────

📝 Description: Retrieve standard inventory stock levels and availability
   ... +8 more lines (see Complete Metadata below)

🏷️  Tags: group:inventory-management

📥 Input Parameters (3 total):
   • filter (string) - optional
     Flexible filter parameter supporting Progress ABL filter expr...
   • skip (integer) - optional
     Records to skip for pagination
   • top (integer) - optional
     Maximum records to return (default 100)

📤 Output Schema: object

📄 Complete Metadata (JSON):
{
  "name": "getInventoryRecords",
  "title": null,
  "description": "Retrieve standard inventory stock levels and availability\n\nContext: ## Filtering & Search...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filter": {
        "type": "string",
        "description": "Flexible filter parameter supporting Progress ABL filter expressions",
        "maxLength": 500
      },
      "skip": {
        "type": "integer",
        "description": "Records to skip for pagination",
        "default": 0,
        "minimum": 0
      },
      "top": {
        "type": "integer",
        "description": "Maximum records to return (default 100)",
        "default": 100,
        "minimum": 1,
        "maximum": 1000
      }
    },
    "required": []
  },
  "outputSchema": {
    "type": "object",
    "properties": { ... }
  },
  "icons": null,
  "annotations": null,
  "meta": {
    "_fastmcp": {
      "tags": ["Inventory Management"]
    }
  }
}
The following table summarizes the information displayed for each tool when you run mcpgen client <profile_name> --list-details.
Element Description
Header Specifies tool number and name with visual separator
Description Specifies smart truncation for long descriptions
Tags Specifies functional grouping and categorization
Input parameters Specifies summary of the first five parameters
Output schema Specifies type of response object
Examples Specifies count if examples are available
Deprecation Specifies warning if the tool is deprecated
Complete JSON Specifies full metadata object for programmatic use

Use cases

Use the following scenarios to understand when and how to leverage the --list-details and related options in the mcpgen client command:
  • API discovery—Quickly identify what each tool does and review the parameters it accepts.

  • Documentation generation—Generate comprehensive documentation by parsing the JSON metadata provided for each tool.

  • Code generation—Use the input and output schema to automatically generate client-side code.

  • Debugging—Inspect exact parameter types, constraints, and default values for troubleshooting.

  • Single tool focus—Apply the --tool option to view details for one specific tool without scrolling through all available tools.

  • Cross-platform compatibility—Use --args-file args.json or --args @args.json syntax to avoid platform-specific issues with inline JSON.

Use the debug option

Use the --debug option to display detailed diagnostic information about HTTP communication and command execution. This option is helpful for troubleshooting issues related to authentication, API responses, or network connectivity.

For example,
  • This command runs the client operation for the specified profile and enables debug mode. Use this command when you want to review the full execution details for general client operations without invoking a specific tool.
    ./mcpgen client <profile_name> --debug
  • This command invokes the listProducts tool for the specified profile, passes arguments to limit the output to three products, and enables debug mode. Use this command when you need to debug a specific tool invocation and inspect the request/response flow.
    ./mcpgen client <profile_name> --tool listProducts --args '{"limit":3}' --debug
Use --debug, when:
  • Investigating authentication or authorization issues
  • Troubleshooting unexpected API responses
  • Verifying headers
  • Debugging downstream HTTP communication
  • Understanding full request/response flow

Service account token selection

Use the --sa-token option to select a specific service account token.

For example:
  • This command runs the client command for the specified profile using the admin service account token. Select this option when you need elevated privileges for listing tools or performing administrative operations.
    ./mcpgen client <profile_name> --sa-token admin
  • This command lists tools for the specified profile using the readonly service account token. Select this option when you want to explore available tools without making changes to the environment.
    ./mcpgen client <profile_name> --sa-token readonly
  • This command invokes the getSupportTickets tool for the specified profile using the admin token and passes arguments to limit the output to five tickets. Select this option when you need to execute a tool that requires administrative privileges and control the number of records returned.
    ./mcpgen client <profile_name> --sa-token admin 
--tool getSupportTickets --args '{"limit":5}'

Notes

  • When listing tools with --tool not specified, both name and description are shown for each tool.
  • --list-json outputs structured JSON for programmatic parsing.
  • When --json is active and no profile is specified, the auto-profile resolution message ([client] Using latest profile: <profile-name>) is suppressed to ensure clean JSON output. This message continues to appear in non-JSON mode.
  • --list-details displays comprehensive tool metadata with beautified output.
  • Smart description truncation for readability.
  • Complete metadata is always available in JSON section.
  • Tool invocation auto-detects JSON output and pretty-prints, unless you provide --raw.
  • File-based arguments support two syntaxes:
    • --args @args.json (shortcut syntax)
    • --args-file args.json (explicit flag)
    Both syntaxes are equivalent and read tool arguments from a JSON file instead of requiring inline JSON.
  • Do not combine --args JSON with --args-file args.json or --args @args.json syntax.
  • Exit code reflects transport/tool success; non-zero indicates failure.
  • Use --sa-token to switch between authorization levels without changing environment variables.
  • Available token names can be seen with ./mcpgen sa-tokens <profile_name>.