DEV Community

Mariano Gobea Alcoba
Mariano Gobea Alcoba

Posted on • Originally published at mgatc.com

Show HN: Mcp2cli – One CLI for every API, 96-99% fewer tokens than native MCP!

#mcp2cli #cli #api #tokens

Introduction

In the realm of Model Control Protocol (MCP) servers, efficiency and token usage are critical considerations. Traditional MCP servers inject their full tool schemas into the context on every turn, which can lead to significant token overhead. For instance, a server with 30 tools would cost approximately 3,600 tokens per turn, even if the model does not use all the tools. Over 25 turns with 120 tools, this can amount to 362,000 tokens just for schemas. This inefficiency is a significant concern, especially in environments where token usage directly impacts costs.

Enter mcp2cli, a command-line interface (CLI) tool designed to address these issues. mcp2cli transforms any MCP server or OpenAPI specification into a CLI at runtime, allowing the language model (LLM) to discover tools on demand. This approach significantly reduces token usage and enhances the overall efficiency of the system. In this article, we will delve into the technical details of mcp2cli, including its architecture, usage, and the benefits it offers.

Architecture of mcp2cli

Overview

mcp2cli operates by dynamically discovering and invoking tools from an MCP server or OpenAPI specification. Instead of loading all tool schemas upfront, it fetches and processes only the necessary information when required. This on-demand discovery mechanism minimizes token usage and improves performance.

Components

  1. CLI Interface: The user interacts with mcp2cli through a simple CLI interface. Commands are structured to mimic traditional CLI tools, making it intuitive for developers to use.
  2. MCP Server Integration: mcp2cli can connect to any MCP server using a WebSocket or HTTP endpoint. It fetches the list of available tools and their schemas as needed.
  3. OpenAPI Specification Handling: mcp2cli supports both local and remote OpenAPI specifications (in JSON or YAML format). It parses the specification to extract tool information and provides a consistent interface for invoking APIs.
  4. Token Management: mcp2cli optimizes token usage by fetching and processing tool schemas only when they are required. This dynamic approach ensures that the model is not burdened with unnecessary context.

Workflow

  1. Initialization: The user starts by specifying the MCP server or OpenAPI specification using the --mcp or --openapi flag.
  2. Tool Discovery: When the user lists available tools or requests help for a specific tool, mcp2cli fetches the necessary information from the server or specification.
  3. Tool Invocation: When a tool is invoked, mcp2cli sends the request to the server and processes the response. The output is presented to the user in a structured format.

Usage Examples

Listing Available Tools

To list all available tools from an MCP server:

mcp2cli --mcp https://mcp.example.com/sse --list
Enter fullscreen mode Exit fullscreen mode

This command fetches the list of tools and displays them, using approximately 16 tokens per tool.

Getting Help for a Specific Tool

To get detailed help for a specific tool:

mcp2cli --mcp https://mcp.example.com/sse create-task --help
Enter fullscreen mode Exit fullscreen mode

This command fetches the schema for the create-task tool and displays the help information, using approximately 120 tokens.

Invoking a Tool

To invoke a tool with specific parameters:

mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug"
Enter fullscreen mode Exit fullscreen mode

This command sends a request to the server to create a task with the specified title, using the minimum necessary tokens.

Using OpenAPI Specifications

mcp2cli can also handle OpenAPI specifications. For example, to list available endpoints from a local OpenAPI file:

mcp2cli --openapi ./api-spec.yaml --list
Enter fullscreen mode Exit fullscreen mode

To get help for a specific endpoint:

mcp2cli --openapi ./api-spec.yaml get-user --help
Enter fullscreen mode Exit fullscreen mode

To invoke an endpoint:

mcp2cli --openapi ./api-spec.yaml get-user --id 123
Enter fullscreen mode Exit fullscreen mode

Token Savings

The primary benefit of mcp2cli is its significant reduction in token usage. By fetching and processing tool schemas on demand, it avoids the overhead of injecting full schemas into the context on every turn. The token savings are substantial, as demonstrated by the following measurements:

  • 30 Tools Over 15 Turns: 96% reduction in token usage.
  • 120 Tools Over 25 Turns: 99% reduction in token usage.

These savings are calculated using the cl100k_base tokenizer and represent a significant improvement in efficiency and cost-effectiveness.

Installation and Setup

Prerequisites

  • Node.js (v14 or later)
  • npm (v6 or later)

Installation

To install mcp2cli, you can use npm:

npm install -g mcp2cli
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can install it as a skill for AI coding agents like Claude Code, Cursor, or Codex:

npx skills add knowsuchagency/mcp2cli --skill mcp2cli
Enter fullscreen mode Exit fullscreen mode

Configuration

After installation, you can configure mcp2cli to connect to your MCP server or OpenAPI specification. For example:

mcp2cli --mcp https://mcp.example.com/sse --list
Enter fullscreen mode Exit fullscreen mode

Or for an OpenAPI specification:

mcp2cli --openapi ./api-spec.yaml --list
Enter fullscreen mode Exit fullscreen mode

Advanced Features

Customization

mcp2cli allows for customization of the CLI interface and behavior. You can define custom commands and flags to suit your specific needs. For example, you can create a custom command to fetch and display a subset of tools:

mcp2cli --mcp https://mcp.example.com/sse --custom-command fetch-tools --filter "type:admin"
Enter fullscreen mode Exit fullscreen mode

Error Handling

mcp2cli includes robust error handling mechanisms to ensure that issues are reported clearly and concisely. For example, if a tool invocation fails, the error message will include the relevant details:

mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug"
Error: Failed to create task. Reason: Invalid task title.
Enter fullscreen mode Exit fullscreen mode

Logging and Debugging

For troubleshooting and debugging, mcp2cli provides logging options. You can enable verbose logging to see detailed information about the requests and responses:

mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug" --verbose
Enter fullscreen mode Exit fullscreen mode

Conclusion

mcp2cli is a powerful tool that addresses the inefficiencies of traditional MCP servers by dynamically discovering and invoking tools on demand. This approach significantly reduces token usage and enhances the overall performance of the system. Whether you are working with an MCP server or an OpenAPI specification, mcp2cli provides a consistent and efficient CLI interface.

By adopting mcp2cli, you can achieve substantial token savings and improve the efficiency of your language models. For more information and consulting services, visit https://www.mgatc.com.

Originally published in Spanish at www.mgatc.com/blog/mcp2cli/

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.