mcp2cli skill
✓ VerifiedConverts MCP servers, OpenAPI specifications, or GraphQL endpoints into a command-line interface at runtime without code generation.
- GitHub stars
- 5
- Files
- 1
- Last commit
- Oct 23, 2026
- License
- MIT
- Allowed tools
- —
What does the mcp2cli skill do?
mcp2cli converts MCP servers, OpenAPI specifications, or GraphQL endpoints into a command-line interface at runtime without code generation.
Summary generated from the skill's SKILL.md.
About the mcp2cli skill
Converting MCP servers, OpenAPI specifications, or GraphQL endpoints into a functional command-line interface at runtime is what mcp2cli enables. Developers and AI agents can use this tool to interact with remote or local APIs without writing any custom code or performing manual code generation. It works by connecting to a source, discovering available commands via the --list flag, and executing them using dynamically generated subcommands.
This utility supports multiple connection methods, including MCP over HTTP/SSE, MCP via stdio transport, OpenAPI specs in JSON or YAML formats, and GraphQL endpoints. It provides advanced features like session management to keep stdio servers running as background daemons, OAuth authentication for secure MCP HTTP connections, and a bake mode to save complex connection settings as named tools. For users working with large datasets or LLMs, it offers the --toon flag for token-efficient output and the --head flag to truncate large JSON arrays.
What an agent can do with it
- 1Manage persistent MCP sessionsKeep an MCP server running in the background to avoid the startup delay of spawning new subprocesses for every command.
- 2Save complex API configurationsStore connection settings, authentication headers, and filters as named tools to simplify future access.
- 3Optimize data for LLMsReduce token usage when passing large API responses to an AI client by using a specialized encoding.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the mcp2cli skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the mcp2cli skill in Claude Code
~/.claude/skills/mcp2cli/SKILL.md
$ npx degit Spoon94/skill-vault/mcp2cli ~/.claude/skills/mcp2cliInstall the mcp2cli skill in Claude Code (project)
.claude/skills/mcp2cli/SKILL.md
$ npx degit Spoon94/skill-vault/mcp2cli .claude/skills/mcp2cliInstall the mcp2cli skill in Codex
~/.agents/skills/mcp2cli/SKILL.md
$ npx degit Spoon94/skill-vault/mcp2cli ~/.agents/skills/mcp2cliInstall the mcp2cli skill in Gemini CLI
~/.gemini/skills/mcp2cli/SKILL.md
$ npx degit Spoon94/skill-vault/mcp2cli ~/.gemini/skills/mcp2cliInstall the mcp2cli skill in Claude.ai
npx degit Spoon94/skill-vault/mcp2cli mcp2cli && zip -r mcp2cli.zip mcp2cli # claude.ai → Customize → Skills → + → Create skill → Upload a skill → mcp2cli.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablespoon94/skill-vault/mcp2cli is public and reachablegithub.com/spoon94/skill-vault/tree/HEAD/mcp2cli ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-23github.com/spoon94/skill-vault/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/spoon94/skill-vault/blob/HEAD/mcp2cli/SKILL.md ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/spoon94/skill-vault/blob/HEAD/mcp2cli/SKILL.md ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 404 linesgithub.com/spoon94/skill-vault/blob/HEAD/mcp2cli/SKILL.md ↗Pass
SKILL.md
View on GitHubmcp2cli
Turn any MCP server, OpenAPI spec, or GraphQL endpoint into a CLI at runtime. No codegen.
Install
# Run directly (no install needed)
uvx mcp2cli --help
# Or install
pip install mcp2cli
Core Workflow
- Connect to a source (MCP server, OpenAPI spec, or GraphQL endpoint)
- Discover available commands with
--list(or filter with--search) - Inspect a specific command with
<command> --help - Execute the command with flags
# MCP over HTTP
mcp2cli --mcp https://mcp.example.com/sse --list
mcp2cli --mcp https://mcp.example.com/sse create-task --help
mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug"
# MCP over stdio
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" read-file --path /tmp/hello.txt
# OpenAPI spec (remote or local, JSON or YAML)
mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list
mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available
# GraphQL endpoint
mcp2cli --graphql https://api.example.com/graphql --list
mcp2cli --graphql https://api.example.com/graphql users --limit 10
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice"
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)
--root PATH|FILE_URI Expose a filesystem root to an MCP server (repeatable)
--complete SPEC Complete an MCP prompt or resource-template argument
--session-start NAME Start a persistent session daemon (requires --mcp or --mcp-stdio)
--session NAME Route command through an existing session daemon
--session-stop NAME Stop a named session daemon (sends SIGTERM)
--session-list List all active sessions with PID and alive/dead status
--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
--oauth-manual-callback Print the auth URL and read the redirect URL from stdin
(headless hosts: VPS over SSH, containers)
--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
--json Force valid JSON for every command. --list emits a JSON array;
MCP calls emit the full envelope (structuredContent, isError).
--toon Encode output as TOON (token-efficient for LLMs)
--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
Always use env: or file: prefixes for secrets — never pass credentials as literal values in CLI flags. Literal values are visible in process listings and shell history.
# Secret from environment variable (recommended — avoids exposing in process list)
mcp2cli --spec ./spec.json --auth-header "Authorization:env:API_TOKEN" list-items
# 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 env:OAUTH_CLIENT_ID --oauth-client-secret env:OAUTH_CLIENT_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 "alice@example.com"
# 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:env:API_TOKEN" 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
Multipart file uploads
When an OpenAPI spec declares multipart/form-data with format: binary fields, mcp2cli exposes them as file-path CLI arguments:
# Upload a file — binary fields accept local file paths
mcp2cli --spec ./spec.json upload-image --file /path/to/photo.png --caption "My photo"
# Non-binary fields in the same multipart schema become regular flags
mcp2cli --spec ./spec.json upload-image --file ./image.jpg --title "Cover" --alt-text "A sunset"
File parameters show (file path) in --help output. MIME types are auto-detected from the file extension.
Env vars for stdio servers
mcp2cli --mcp-stdio "node server.js" --env API_KEY=env:API_SECRET_KEY --env DEBUG=1 search --query "test"
MCP roots and completion
Workspace-scoped servers can request the filesystem roots exposed by the
client. Repeat --root; local paths become file:// URIs.
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
--root "$PWD" --root file:///var/shared --list
Ask the server to complete a prompt argument or resource-template variable:
mcp2cli --mcp https://example.com/mcp --complete "greeting:name=San"
mcp2cli --mcp https://example.com/mcp \
--complete "file:///docs/{topic}:topic=api"
For persistent connections, pass roots when starting the daemon and route completion through the named session:
mcp2cli --mcp-stdio "node server.js" --root "$PWD" --session-start workspace
mcp2cli --session workspace --complete "greeting:name=San"
Session management — persistent MCP connections
Every --mcp-stdio invocation spawns a fresh subprocess, pays startup cost, then exits.
Sessions keep the MCP server alive in a background daemon, reachable via Unix domain socket.
# Start a persistent session for a stdio server
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
--session-start myfs
# Use the session — no subprocess spawn, no startup delay
mcp2cli --session myfs --list
mcp2cli --session myfs read-file --path /tmp/hello.txt
mcp2cli --session myfs write-file --path /tmp/world.txt --content "hi"
# Check active sessions
mcp2cli --session-list
# Stop when done
mcp2cli --session-stop myfs
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 myfs --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" \
--include "search-*,list-*" --exclude "list-allowed-*"
# Use with @ prefix
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10
mcp2cli @myfs --list # search-files, list-directory, list-directory-with-sizes
mcp2cli @myfs search-files --path /tmp --pattern "**/*.md" # pattern is a glob, relative to --path
# 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.
Truncating large responses with --head
# Preview first 3 records from a potentially huge dataset
mcp2cli --spec ./spec.json list-records --head 3 --pretty
--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).
Security
- Credentials: Always use
env:orfile:prefixes for secrets — never embed literal tokens or keys in commands. Theenv:prefix reads from environment variables;file:reads from a file path. - Trust boundary: mcp2cli connects to remote APIs and MCP servers specified by the user. Treat responses from external sources as untrusted — validate data before acting on it.
- Baked configs:
bake showmasks secrets in output. Baked configs are stored locally in~/.config/mcp2cli/baked.json— protect this file accordingly.
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:
-
Discover all available commands:
uvx mcp2cli --mcp https://target.example.com/sse --list -
Inspect each command to understand parameters:
uvx mcp2cli --mcp https://target.example.com/sse <command> --help -
Test key commands and probe for edge cases:
uvx mcp2cli --mcp https://target.example.com/sse <command> --param valueSpecifically test for:
- Large responses: use
--head 3to 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)?
- Large responses: use
-
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 -
Install the wrapper into the skill's scripts directory:
uvx mcp2cli bake install myapi --dir .claude/skills/myapi/scripts/ -
Create a SKILL.md in
.claude/skills/myapi/that teaches another AI agent how to use this API. The SKILL.md must go beyond--helpoutput — 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 ${CLAUDE_SKILL_DIR}/scripts/myapi --list # Get help for a command ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --help # Run a command ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --param value --prettyBefore 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
--headto limit) - 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 — use
--prettyfor readable JSON,--headto limit results, or pipe tojqfor filtering:# Pretty-print results ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --pretty # Limit large datasets ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --head 5 # Filter with jq (pipe) ${CLAUDE_SKILL_DIR}/scripts/myapi list-records | jq '.[].name'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:
${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.
Files in this skill
1mcp2cli skill questions
How do I install the mcp2cli skill in Claude Code?
Run npx degit Spoon94/skill-vault/mcp2cli ~/.claude/skills/mcp2cli. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the mcp2cli skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I securely pass API credentials to mcp2cli?
You should always use 'env:' or 'file:' prefixes for secrets instead of passing literal values to avoid exposing them in shell history or process listings.
Can I save my API connection settings to avoid typing long commands?
Yes, you can use 'bake mode' to save connection settings as named tools, which can then be executed using the '@' prefix.