DOCSEARCHbyAlgolia
Submit Docs

mcp2cli

repository·main·Indexed 25 days ago

https://github.com/knowsuchagency/mcp2cli

A CLI tool that turns MCP servers, OpenAPI specifications, or GraphQL endpoints into functional CLIs at runtime without code generation. It features OAuth support, secure secret handling via environment variables or files, and a 'bake' command to save connection settings as named tools. Designed for AI agents, it provides token-efficient output formats like TOON and optimized tool listing to reduce LLM token costs.

Tokens
11.9K
Snippets
27
Records
56
Agent score
81%

What's inside mcp2cli

  1. Use Bake mode to save API configurations

    main

    Bake mode allows you to save connection settings (like OpenAPI specs or MCP commands) as named tools to avoid repeating long flag sets. Saved configurations are stored in ~/.config/mcp2cli/baked.json (can be overridden via MCP2CLI_CONFIG_DIR).

    Commands

    • bake create NAME [opts]: Save a new configuration. Use --include (glob whitelist) or --exclude (glob blacklist) to filter tools, and --methods (for OpenAPI) to limit HTTP methods.
    • bake list: List all saved tools.
    • bake show NAME: Show configuration (secrets are masked).
    • bake update NAME [opts]: Update an existing tool.
    • bake remove NAME: Delete a tool.
    • bake install NAME: Create a ~/.local/bin/NAME wrapper script.
    • @NAME [args]: Run a saved tool directly.

    Example

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

# Run the tool using the @ prefix
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10

  2. Manage persistent MCP sessions for stdio servers

    main

    Every --mcp-stdio invocation normally spawns a fresh subprocess that exits after the command runs. To avoid startup costs and keep the server alive, use Sessions to run the MCP server as a background daemon reachable via a Unix domain socket.

    Workflow

    1. Start a session: mcp2cli --mcp-stdio "<CMD>" --session-start <NAME>
    2. Use the session: mcp2cli --session <NAME> <command>
    3. List active sessions: mcp2cli --session-list
    4. Stop the session: mcp2cli --session-stop <NAME>

    Example

    # Start a persistent session for a filesystem server
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  --session-start myfs
 
# Use the session without subprocess spawn delay
mcp2cli --session myfs --list
mcp2cli --session myfs read-file --path /tmp/hello.txt
 
# Check active sessions
mcp2cli --session-list
 
# Stop when done
mcp2cli --session-stop myfs

  3. Securely handle authentication with env: and file: prefixes

    main

    To prevent credentials from appearing in process listings or shell history, never pass secrets as literal values in CLI flags. Instead, use the env: or file: prefixes.

    • env:VAR_NAME: Reads the value from an environment variable.
    • file:/path/to/file: Reads the value from a file.

    Examples

    Using an environment variable

    mcp2cli --spec ./spec.json --auth-header "Authorization:env:API_TOKEN" list-items

    Using a file

    mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "x-api-key:file:/run/secrets/api_key" \
  search --query "test"
    mcp2cli --spec ./spec.json --auth-header "Authorization:env:API_TOKEN" list-items

  4. Use Bake mode to save connection settings

    main

    Bake mode allows you to save complex connection settings (like URLs, auth headers, and OAuth config) as named tools for easy reuse.

    • bake create NAME [opts]: Save connection settings as a named tool.
    • bake list: List all saved (baked) tools.
    • bake show NAME: Show the configuration for a tool (secrets are masked).
    • bake update NAME [opts]: Update an existing baked tool.
    • bake remove NAME: Delete a baked tool.
    • bake install NAME: Create a wrapper script in ~/.local/bin for the tool.
    • @NAME [args]: Run a baked tool directly using the @ prefix (e.g., mcp2cli @petstore --list).

  5. Use OAuth authentication

    main

    mcp2cli supports OAuth across MCP, OpenAPI, and GraphQL modes, handling token acquisition, caching, and refresh automatically. Tokens are persisted in ~/.cache/mcp2cli/oauth/.

    # Authorization code + PKCE flow (opens browser for login)
mcp2cli --mcp https://mcp.example.com/sse --oauth --list
mcp2cli --spec https://api.example.com/openapi.json --oauth --list
mcp2cli --graphql https://api.example.com/graphql --oauth --list

# Client credentials flow (machine-to-machine, no browser)
mcp2cli --spec https://api.example.com/openapi.json \
  --oauth-client-id "my-client-id" \
  --oauth-client-secret "my-secret" \
  list-pets

# With specific scopes
mcp2cli --graphql https://api.example.com/graphql --oauth --oauth-scope "read write" users

# Local spec file — use --base-url for OAuth discovery
mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list

  6. Configure OAuth authentication for MCP HTTP

    main

    For MCP servers over HTTP, you can use OAuth via the --oauth flag. This supports both Authorization Code + PKCE (which opens a browser) and Client Credentials (machine-to-machine).

    Authorization code + PKCE

    mcp2cli --mcp https://mcp.example.com/sse --oauth --list

    Client credentials

    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 specific scopes

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

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

    mcp2cli --mcp https://mcp.example.com/sse --oauth --list

  7. Bake connection settings into named tools

    main

    Use the bake command to save connection settings (like --spec, --mcp, or --mcp-stdio and auth flags) into a named configuration. You can then invoke these tools using the @ prefix.

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

# Create a baked tool from an MCP stdio server
mcp2cli bake create mygit --mcp-stdio "npx @mcp/github" \
  --include "search-*,list-*" --exclude "delete-*"

# Use a baked tool with @ prefix — no connection flags needed
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10

mcp2cli bake list                         # show all baked tools
mcp2cli bake show petstore                # show config (secrets masked)
mcp2cli bake update petstore --cache-ttl 3600
mcp2cli bake remove petstore
mcp2cli bake install petstore             # creates ~/.local/bin/petstore wrapper
mcp2cli bake install petstore --dir ./scripts/  # install wrapper to custom directory

  8. Create a SKILL.md for an API Skill

    main

    A SKILL.md file is required in the skill directory (e.g., .claude/skills/myapi/) to teach an AI agent how to use the baked API wrapper.

    Recommended Structure

    1. Frontmatter: Define the name, description, and allowed tools.

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

    2. Core Workflow: Provide the exact commands for discovery and execution using the ${CLAUDE_SKILL_DIR} variable.

    # 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 --pretty

    3. Decision Framework (Before Querying): Include a checklist for the agent, such as checking for pagination requirements (--offset, --limit) or large output fields that need truncation (--head).

    4. Anti-Patterns & Gotchas: Document surprises found during testing, such as date syntax quirks, parameter inconsistencies, or binary export risks.

    5. Output Processing: Show how to use --pretty for readability, --head for limiting, or piping to jq for 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'

    6. Export Formats: If the API supports non-JSON formats, document them and note if they are text-safe or binary. For binary formats, use the --raw flag to avoid corruption:

    ${CLAUDE_SKILL_DIR}/scripts/myapi export --format xlsx --raw > output.xlsx

    The Knowledge Delta Principle

    Do not simply duplicate the --help output. Focus on the Knowledge Delta: parameters that actually matter, surprising default behaviors, incompatible combinations, and rate limits.

  9. Develop and test mcp2cli

    main

    For contributors, the project uses uv for dependency management and pytest for testing.

    To install with test and MCP dependencies:

    uv sync --extra test

    To run the full test suite (96 tests covering OpenAPI, MCP stdio, MCP HTTP, caching, and token savings):

    uv run pytest tests/ -v

    To run only the token savings tests:

    uv run pytest tests/test_token_savings.py -v -s
    uv sync --extra test
uv run pytest tests/ -v

  10. Optimize output for LLMs with --toon and --head

    main

    When working with large datasets or providing data to LLMs, use these flags to manage token usage and response size.

    • --toon: Encodes output as TOON, which is a token-efficient format for LLMs. This can reduce token usage by 40-60% for large uniform arrays.
    • --head N: Slices JSON arrays to the first N elements. This is useful for previewing large datasets or preventing context window overflow.

    Examples

    Using TOON for efficiency

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

    Truncating large responses

    mcp2cli --spec ./spec.json list-records --head 3 --pretty
    mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

  11. Core Workflow for interacting with APIs and MCP servers

    main

    The standard workflow for using mcp2cli involves four steps:

    1. Connect to a source (MCP server, OpenAPI spec, or GraphQL endpoint).
    2. Discover available commands using the --list flag (or filter them with --search).
    3. Inspect a specific command's usage with <command> --help.
    4. Execute the command with the required flags.

    Examples

    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

    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 --mcp https://mcp.example.com/sse --list

  12. Install mcp2cli as an AI Agent Skill

    main

    You can install an official skill that teaches AI coding agents (like Claude Code, Cursor, or Codex) how to use mcp2cli. Once installed, agents can discover and call MCP servers or OpenAPI endpoints, and even generate new skills from APIs.

    npx skills add knowsuchagency/mcp2cli --skill mcp2cli