mcp2cli

CLI Reference

mcp2cli [global options] <subcommand> [command options]

Source (mutually exclusive, one required):
  --spec URL|FILE       OpenAPI spec (JSON or YAML, local or remote)
  --mcp URL             MCP server URL (HTTP/SSE)
  --mcp-stdio CMD       MCP server command (stdio transport)
  --graphql URL         GraphQL endpoint URL

Options:
  --auth-header K:V       HTTP header (repeatable, value supports env:/file: prefixes)
  --base-url URL          Override base URL from spec
  --transport TYPE        MCP HTTP transport: auto|sse|streamable (default: auto)
  --env KEY=VALUE         Env var for stdio server process (repeatable)
  --oauth                 Enable OAuth (authorization code + PKCE flow)
  --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
  --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)
  --oauth-scope SCOPE     OAuth scope(s) to request
  --cache-key KEY         Custom cache key
  --cache-ttl SECONDS     Cache TTL (default: 3600)
  --refresh               Bypass cache
  --list                  List available subcommands
  --search PATTERN        Search tools by name or description (implies --list)
  --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
  --pretty                Pretty-print JSON output
  --raw                   Print raw response body
  --toon                  Encode output as TOON (token-efficient for LLMs)
  --jq EXPR               Filter JSON output through jq expression
  --head N                Limit output to first N records (arrays)
  --version               Show version

Bake mode:
  bake create NAME [opts]   Save connection settings as a named tool
  bake list                 List all baked tools
  bake show NAME            Show config (secrets masked)
  bake update NAME [opts]   Update a baked tool
  bake remove NAME          Delete a baked tool
  bake install NAME         Create ~/.local/bin wrapper script
  @NAME [args]              Run a baked tool (e.g. mcp2cli @petstore --list)

Subcommands and flags are generated dynamically from the source.

Patterns

Authentication

# API key header (literal value)
mcp2cli --spec ./spec.json --auth-header "Authorization:Bearer tok_..." list-items

# Secret from environment variable (avoids exposing in process list)
mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "Authorization:env:API_TOKEN" \
  search --query "test"

# Secret from file
mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "x-api-key:file:/run/secrets/api_key" \
  search --query "test"

OAuth authentication (MCP HTTP only)

# Authorization code + PKCE (opens browser)
mcp2cli --mcp https://mcp.example.com/sse --oauth --list

# Client credentials (machine-to-machine)
mcp2cli --mcp https://mcp.example.com/sse \
  --oauth-client-id "my-id" --oauth-client-secret "my-secret" \
  search --query "test"

# With scopes
mcp2cli --mcp https://mcp.example.com/sse --oauth --oauth-scope "read write" --list

Tokens are cached in ~/.cache/mcp2cli/oauth/ and refreshed automatically.

Transport selection (MCP HTTP only)

# Default: tries streamable HTTP, falls back to SSE
mcp2cli --mcp https://mcp.example.com/sse --list

# Force SSE transport (skip streamable HTTP attempt)
mcp2cli --mcp https://mcp.example.com/sse --transport sse --list

# Force streamable HTTP (no SSE fallback)
mcp2cli --mcp https://mcp.example.com/sse --transport streamable --list

GraphQL

# Discover queries and mutations
mcp2cli --graphql https://api.example.com/graphql --list

# Run a query
mcp2cli --graphql https://api.example.com/graphql users --limit 10

# Run a mutation
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice" --email "[email protected]"

# Override auto-generated selection set
mcp2cli --graphql https://api.example.com/graphql users --fields "id name email"

# With auth
mcp2cli --graphql https://api.example.com/graphql --auth-header "Authorization:Bearer tok_..." users

Tool search

# Filter tools by name or description (case-insensitive)
mcp2cli --mcp https://mcp.example.com/sse --search "task"
mcp2cli --spec ./openapi.json --search "create"
mcp2cli --graphql https://api.example.com/graphql --search "user"

--search implies --list — shows only matching tools.

POST with JSON body from stdin

echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

Env vars for stdio servers

mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 search --query "test"

Bake mode — saved configurations

Save connection settings as named configurations to avoid repeating flags:

# Create a baked tool
mcp2cli bake create petstore --spec https://api.example.com/spec.json \
  --exclude "delete-*,update-*" --methods GET,POST --cache-ttl 7200

mcp2cli bake create mygit --mcp-stdio "npx @mcp/github" \
  --include "search-*,list-*" --exclude "delete-*"

# Use with @ prefix
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10

# Manage
mcp2cli bake list
mcp2cli bake show petstore
mcp2cli bake update petstore --cache-ttl 3600
mcp2cli bake remove petstore
mcp2cli bake install petstore    # creates ~/.local/bin/petstore wrapper

Filter options: --include (glob whitelist), --exclude (glob blacklist), --methods (HTTP methods, OpenAPI only).

Configs stored in ~/.config/mcp2cli/baked.json (override with MCP2CLI_CONFIG_DIR).

Caching

Specs and MCP tool lists are cached in ~/.cache/mcp2cli/ (1h TTL). Local files are never cached.

mcp2cli --spec https://api.example.com/spec.json --refresh --list    # Force refresh
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list  # 24h TTL

TOON output (token-efficient for LLMs)

mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

Best for large uniform arrays — 40-60% fewer tokens than JSON.

JSON filtering with --jq

Prefer --jq over Python scripts for JSON processing — it uses fewer tokens and avoids script overhead.

# Extract specific fields
mcp2cli --spec ./spec.json list-pets --jq '.[].name'

# Count results
mcp2cli --mcp https://example.com/sse list-items --jq 'length'

# Complex filtering
mcp2cli --spec ./spec.json list-pets --jq '[.[] | select(.status == "available")] | length'

# Preview large datasets (--head truncates before --jq processes)
mcp2cli --spec ./spec.json list-records --head 3 --jq '.'

Truncating large responses with --head

# Preview first 3 records from a potentially huge dataset
mcp2cli --spec ./spec.json list-records --head 3 --pretty

# Combine with --jq for targeted inspection
mcp2cli --spec ./spec.json list-records --head 1 --jq 'keys'

--head N slices JSON arrays to the first N elements. Useful for datasets with oversized fields (e.g. geo_shape polygons at ~200KB per record).

Generating a Skill from an API

When the user asks to create a skill from an MCP server, OpenAPI spec, or GraphQL endpoint, follow this workflow:

1. Discover all available commands:

   uvx mcp2cli --mcp https://target.example.com/sse --list
   

2. Inspect each command to understand parameters:

   uvx mcp2cli --mcp https://target.example.com/sse <command> --help
   

3. Test key commands and probe for edge cases:

   uvx mcp2cli --mcp https://target.example.com/sse <command> --param value
   

   Specifically test for:

   • Large responses: use --head 3 to preview — do any fields produce oversized output (e.g. geo_shape, embedded blobs)?
   • Date/time fields: what format does the API expect? (ISO 8601, Unix timestamps, custom syntax like date'2022'?)
   • Pagination: does the API return all results or require --offset/--limit?
   • Error messages: what happens with invalid parameters? Are errors informative?
   • Binary vs text responses: do any endpoints return non-JSON (xlsx, parquet, images)?
   • Scope confusion: does the data contain more than expected (e.g. national data when you expect regional)?

4. Bake the connection settings so the skill doesn't need to repeat flags:

   uvx mcp2cli bake create myapi \
     --mcp https://target.example.com/sse \
     --auth-header "Authorization:Bearer env:MYAPI_TOKEN" \
     --exclude "delete-*" --methods GET,POST
   

5. Install the wrapper into the skill's scripts directory:

   uvx mcp2cli bake install myapi --dir .claude/skills/myapi/scripts/
   

6. Create a SKILL.md in .claude/skills/myapi/ that teaches another AI agent how to use this API. The SKILL.md must go beyond --help output — focus on knowledge that can only be learned through testing and reading documentation.

   Frontmatter:

   ---
   name: myapi
   description: Interact with the MyAPI service
   allowed-tools: Bash(bash *)
   ---
   

   Core Workflow (discovery + execution):

   # List available commands
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi --list
   # Get help for a command
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --help
   # Run a command
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --param value --pretty
   

   Before Querying checklist — include a decision framework:

   • What dataset/resource am I targeting?
   • Do I need pagination (--offset, --limit)?
   • Are there fields that produce large output I should exclude or truncate (--head)?
   • What date/filter format does this endpoint expect?

   Anti-Patterns & Gotchas — document every surprise found during testing:

   • Date syntax quirks (e.g. date'2022' vs "2022")
   • Fields that produce oversized output (e.g. geo_shape → use --head or --jq to exclude)
   • Parameter name inconsistencies across endpoints
   • Scope/filtering confusion (e.g. dataset contains national data, not just regional)
   • Binary export corruption risks (e.g. don't pipe binary formats through text encoding)

   Output Processing — recommend --jq over Python for JSON filtering:

   # Extract specific fields
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --jq '.[].name'
   # Count results
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --jq 'length'
   # Filter by condition
   bash ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --jq '[.[] | select(.status == "active")]'
   

   Prefer --jq over piping to Python for JSON processing — it is more token-efficient and avoids unnecessary script complexity.

   Export Formats (if the API supports multiple output types):

   • List supported formats (JSON, CSV, xlsx, parquet, etc.)
   • Note which are text-safe vs binary
   • For binary formats: bash ${CLAUDE_SKILL_DIR}/scripts/myapi export --format xlsx --raw > output.xlsx

   Knowledge Delta Principle: Do not duplicate parameter listings from --help. Instead, document which parameters actually matter for common tasks, default behaviors that are surprising, combinations that don't work, and rate limits or response size limits.

The generated skill uses mcp2cli as its execution layer — the baked wrapper script handles all connection details so the SKILL.md stays clean and portable.