Runtime zero-codegen CLI generator for MCP servers, OpenAPI specs, and GraphQL endpoints, optimized for minimizing tool schema token waste in AI Agent workflows.
mcp2cli is a Python CLI tool that dynamically converts any MCP server (HTTP/SSE/stdio), OpenAPI spec (JSON/YAML), or GraphQL endpoint into a command-line interface at runtime without code generation. Its core value lies in solving the token waste problem caused by AI agents carrying full tool schemas in every conversation round, claiming 96–99% schema token savings.
Protocol Access#
Four access modes: --mcp URL (MCP HTTP/SSE with auto/sse/streamable transport), --mcp-stdio CMD (stdio subprocess communication), --spec URL|FILE (local or remote OpenAPI JSON/YAML), --graphql URL (auto introspection to discover queries/mutations and generate selection sets).
Token Optimization#
- Schema-free transmission: Agents only pass CLI command lines instead of full tool schemas
- Tool list compression:
--list --top N --compactcompresses 96 tools to ~20 tokens - TOON output: LLM-friendly encoding format, 40–60% more compact than JSON for large arrays
Authentication & Security#
Built-in OAuth Authorization Code + PKCE and Client Credentials flows with automatic token caching and refresh. env: and file: prefixes read sensitive values from environment variables or files, keeping them out of process argument lists.
User Experience Features#
- Bake mode: Persist spec URL + auth configs as named tools (e.g.,
@petstore) for one-command invocation - Usage-aware sorting: Locally tracks call frequency;
--listdefaults to frequency-based ordering - Search & filtering:
--searchfor fuzzy matching;--include/--excludefor glob-based whitelisting/blacklisting - Caching: Specs and tool lists cached in
~/.cache/mcp2cli/with 1-hour default TTL - AI Agent Skill: Installable skill in skills.sh format for Claude Code, Cursor, Codex, etc.
Architecture#
Entry point: mcp2cli:main. Core code in src/mcp2cli/, tests in tests/ (96 test cases). Minimal core dependencies: httpx, mcp>=1.0, PyYAML. Requires Python >= 3.10, distributed via PyPI (v3.0.2, MIT license, built with uv_build). All subcommand construction happens in memory with no intermediate code files. Config persistence paths: ~/.config/mcp2cli/baked.json (Bake config), ~/.cache/mcp2cli/oauth/ (OAuth tokens), ~/.cache/mcp2cli/usage.json (usage data), all overridable via environment variables.
Installation & Quick Start#
uvx mcp2cli --help
uv tool install mcp2cli
pip install mcp2cli
mcp2cli --mcp https://mcp.example.com/sse --list
mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json list-pets --status available
mcp2cli --graphql https://api.example.com/graphql users --limit 10
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list
Unconfirmed Items#
- Specific benchmark methodology for the "96–99% token savings" claim is not detailed in the README
- TOON format encoding specification is not documented in the README
- No formal GitHub Releases published; versions distributed via PyPI only
- Encryption or permission protection for persisted auth configs in Bake mode is not documented