Install

```bash

Run directly without installing

uvx mcp2cli --help

Or install globally

uv tool install mcp2cli ```

Install with test + MCP deps

uv sync --extra test

Usage

Usage-aware tool ranking

mcp2cli tracks tool invocations locally and uses that data to rank --list output, reducing token costs for LLM agents working with large servers.

```bash

Secrets from environment or files

Sensitive values (--auth-header values, --oauth-client-id, --oauth-client-secret) support env: and file: prefixes to avoid passing secrets as CLI arguments (which are visible in process listings):

```bash

Read from environment variable

mcp2cli --mcp https://mcp.example.com/sse \ --auth-header "Authorization:env:MY_API_TOKEN" \ --list

Works with secret managers that inject env vars

fnox exec -- mcp2cli --mcp https://mcp.example.com/sse \ --oauth-client-id "env:OAUTH_CLIENT_ID" \ --oauth-client-secret "env:OAUTH_CLIENT_SECRET" \ --list ```

Pass environment variables to the server process

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

Bake mode — save connection settings

Tired of repeating --spec/--mcp/--mcp-stdio plus auth flags on every invocation? Bake them into a named configuration:

```bash

MCP tool calls emit the FULL CallToolResult envelope — including

OpenAPI mode

```bash

Call an endpoint

mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available

List all queries and mutations from a GraphQL endpoint

mcp2cli --graphql https://api.example.com/graphql --list

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

OpenAPI / GraphQL calls emit the response as JSON (non-JSON bodies become a JSON string)

mcp2cli --spec ./openapi.json --json list-pets mcp2cli --graphql https://api.example.com/graphql --json users ```

--json takes precedence over --raw and --toon (both of which can produce non-JSON), so it always wins — that is what makes it a reliable "force JSON" switch. Indentation follows the usual rule: pretty on a TTY or with --pretty, compact when piped.

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 MCP stdio server (repeatable)
  --root PATH|FILE_URI    Expose a filesystem root to an MCP server (repeatable)
  --complete SPEC         Complete an MCP prompt or resource-template argument
  --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 from stdin
                          (for hosts with no reachable browser)
  --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)
  --sort MODE             Sort --list output: usage|recent|alpha|default
  --top N                 Show only the top N tools in --list output
  --compact               Space-separated tool names only, no descriptions
  --verbose               Show full tool descriptions (unwrapped)
  --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 output for every command (--list and tool
                          calls). MCP calls emit the full result envelope including
                          structuredContent. Takes precedence over --raw and --toon.
  --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 their flags are generated dynamically from the spec or MCP server tool definitions. Run <subcommand> --help for details.

For token savings analysis, architecture details, and comparison to Anthropic's Tool Search, see the full writeup on the OCAI blog.

MCP SDK compatibility

mcp2cli works with both major versions of the MCP Python SDK (mcp>=1.26,<3), so it never forces a resolver conflict with other tools in the same environment. CI runs the suite against the declared floor, the latest 1.x, and the latest 2.x.

The two majors differ in ways that matter to a client — v2 renamed model fields to snake_case, replaced streamablehttp_client, moved to httpx2, and dropped the session-id element from the transport tuple. Those differences are confined to a handful of helpers (_mcp_attr, _mcp_dump, _streamable_streams, _list_tools_page, _resource_uri, _authorization_code_result); the rest of the codebase is version-agnostic. The test fixtures speak the JSON-RPC wire protocol directly and import no SDK, so they hold across majors.

---