MCP2CLI — Agent Zero Plugin

Token-efficient CLI bridge to any MCP server. Instead of injecting all MCP tool schemas into every LLM turn, agents discover and call tools on demand — saving 96–99% of tokens compared to native MCP injection.

The Problem with Native MCP in Agent Zero

When you add MCP servers to Agent Zero's settings and leave them enabled, the framework injects all tool schemas from every server into the system prompt on every single turn. A typical MCP server exposes 20–50 tools, each with a full JSON schema description.

The solution: configure your MCP servers in Agent Zero settings but set them to "disabled": true. This keeps their connection details available for mcp2cli to use, without injecting their schemas into context.

Setup

Step 1 — Install the Plugin

1. Enable MCP2CLI in Agent Zero → Settings → Agent tab
2. Click Initialize to install the mcp2cli binary
   • Falls back to uvx mcp2cli automatically if pip install fails
   • No extra steps needed if uvx is available

Step 2 — Configure MCP Servers (with disabled: true)

Open Agent Zero → Settings → MCP tab and add your servers. The key is to set "disabled": true on each server so their schemas are not injected into the system prompt, while their connection config remains available to the mcp2cli tool.

Example mcpServers configuration in Agent Zero settings:

{
  "mcpServers": {
    "gtm": {
      "command": "npx",
      "args": ["gtm-mcp"],
      "env": {
        "GTM_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GTM_TOKEN_FILE": "/path/to/token.json"
      },
      "disabled": true
    },
    "deep-wiki": {
      "url": "https://mcp.deepwiki.com/mcp",
      "type": "streamable-http",
      "disabled": true
    }
  }
}

⚠️ "disabled": true is the key setting. It tells Agent Zero to skip native schema injection for that server. The mcp2cli tool reads the same config and connects on demand — you get all the functionality with none of the context pollution.

Step 3 — Use the mcp2cli Tool

Agents automatically have access to the mcp2cli tool. The plugin injects a skill hint into the system prompt reminding agents to load the mcp2cli skill for detailed usage instructions.

Usage Workflow

Always follow this 4-step discovery pattern — never assume tool names:

1. See configured servers

{
    "tool_name": "mcp2cli",
    "tool_args": {}
}

2. List tools on a server

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "server": "gtm",
        "action": "list"
    }
}

Or search by keyword:

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "server": "gtm",
        "action": "search",
        "search_query": "tag"
    }
}

3. Inspect a tool's parameters

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "server": "gtm",
        "action": "help",
        "tool_name": "list-gtm-tags"
    }
}

4. Call the tool

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "server": "gtm",
        "action": "call",
        "tool_name": "list-gtm-tags",
        "params": "{\"account-id\": \"123456\", \"container-id\": \"789\"}"
    }
}

Ad-hoc Connections

Connect to any MCP server without pre-configuring it in settings:

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "mcp_url": "https://mcp.deepwiki.com/mcp",
        "action": "list"
    }
}

{
    "tool_name": "mcp2cli",
    "tool_args": {
        "mcp_stdio": "npx some-mcp-server",
        "mcp_env": "API_KEY=sk-abc,DEBUG=1",
        "action": "list"
    }
}

Tool Arguments Reference

Supported Server Types

Requirements

• Agent Zero with MCP support
• mcp2cli binary (installed via Initialize) or uvx (zero-install fallback)
• Node.js (only for stdio servers using npx)

License

MIT — see LICENSE