MCP Client CLI Guide

MCP Client CLI Guide

This guide documents how to interact with MCP servers and manage A2A agents using the command-line interface.

Table of Contents

• Overview
• A2A Agent Management
• MCP Client Authentication
• Basic Commands
• Server Management Commands
• Tool Discovery
• Direct Server Access

Overview

Two CLI tools are available:

1. agent_mgmt.py - A2A agent management (register, modify, delete, list)
2. mcp_client.py - MCP server interaction (list tools, call tools, etc.)

A2A Agent Management

For complete A2A agent management documentation, see: A2A Agent Management Guide

Quick start with the mcp-gateway-m2m service account:

# Register an agent
uv run python cli/agent_mgmt.py register cli/examples/code_reviewer_agent.json

# List all agents
uv run python cli/agent_mgmt.py list

# Test agent
uv run python cli/agent_mgmt.py test /code-reviewer

MCP Client Authentication

The client supports two authentication methods:

1. M2M (Machine-to-Machine) Authentication with mcp-gateway-m2m

The primary M2M account mcp-gateway-m2m is auto-configured. Set environment variables:

export CLIENT_ID=mcp-gateway-m2m
export CLIENT_SECRET=<generated-during-init>
export KEYCLOAK_URL=http://localhost:8080
export KEYCLOAK_REALM=mcp-gateway

Or use the auto-generated token from mcp-gateway-m2m:

source <(python3 -c "import json; d=json.load(open('.oauth-tokens/ingress.json')); print('TOKEN=' + d['access_token'])")

2. Ingress Token Authentication

The client will automatically load ingress tokens from .oauth-tokens/ingress.json if M2M credentials are not available. This token comes from the mcp-gateway-m2m service account.

Basic Commands

Test Connectivity (Ping)

# Ping the default gateway
uv run cli/mcp_client.py ping

# Ping a specific endpoint
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp ping

List Available Tools

# List tools from the default gateway
uv run cli/mcp_client.py list

# List tools from a specific server
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp list

Server Management Commands

List All Registered Services

uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool list_services \
  --args '{}'

Returns a dictionary containing:

• services: List of service information with details like name, path, status
• total_count: Total number of registered services

Register a New Service

uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool register_service \
  --args '{
    "server_name": "Minimal Server",
    "path": "/minimal-server",
    "proxy_pass_url": "http://minimal-server:8000",
    "description": "A minimal MCP server example",
    "tags": ["example", "minimal"],
    "num_tools": 2,
    "num_stars": 0,
    "is_python": true,
    "license": "MIT"
  }'

Register from a JSON file:

# Register a service using configuration from a JSON file
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool register_service \
  --args "$(cat cli/examples/server-config.json)"

Required parameters:

• server_name: Display name for the server
• path: Unique URL path prefix (must start with '/')
• proxy_pass_url: Internal URL where the MCP server is running

Optional parameters:

• description: Description of the server (default: "")
• tags: List of tags for categorization (default: null)
• num_tools: Number of tools provided (default: 0)
• num_stars: Star rating for the server (default: 0)
• is_python: Whether implemented in Python (default: false)
• license: License information (default: "N/A")

Remove a Service

uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool remove_service \
  --args '{"service_path": "/my-service"}'

Example:

# Remove minimal-server
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool remove_service \
  --args '{"service_path": "/minimal-server"}'

Toggle Service State (Enable/Disable)

uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool toggle_service \
  --args '{"service_path": "/my-service"}'

Health Check

Get health status for all registered servers:

uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool healthcheck \
  --args '{}'

Tool Discovery

Find Tools Using Natural Language

Use the intelligent tool finder to discover tools based on natural language queries:

# Find tools for getting current time
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool intelligent_tool_finder \
  --args '{"natural_language_query": "get current time in New York", "top_n_tools": 3}'

# Find tools by tags only
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool intelligent_tool_finder \
  --args '{"tags": ["time", "timezone"], "top_n_tools": 5}'

# Combine natural language and tags
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool intelligent_tool_finder \
  --args '{
    "natural_language_query": "get current time",
    "tags": ["time"],
    "top_k_services": 3,
    "top_n_tools": 5
  }'

Parameters:

• natural_language_query: Natural language description (optional if tags provided)
• tags: List of tags to filter by (optional)
• top_k_services: Number of top services to consider (default: 3)
• top_n_tools: Number of best tools to return (default: 1)

Direct Server Access

Call Tools on Specific Servers

Current Time Service

# Get current time in a specific timezone
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \
  --tool current_time_by_timezone \
  --args '{"tz_name": "America/New_York"}'

# Use default timezone (America/New_York)
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \
  --tool current_time_by_timezone \
  --args '{}'

Command Structure

General Format

uv run cli/mcp_client.py [--url URL] COMMAND [--tool TOOL_NAME] [--args JSON_ARGS]

Parameters

• --url: Gateway or server URL (default: http://localhost/mcpgw/mcp)
• command: One of ping, list, or call
• --tool: Tool name (required for call command)
• --args: Tool arguments as JSON string (for call command)

Examples Summary

Quick Server Management

# List all services
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call --tool list_services --args '{}'

# Register a new service
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool register_service \
  --args '{"server_name": "Minimal Server", "path": "/minimal-server", "proxy_pass_url": "http://minimal-server:8000"}'

# Remove a service
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool remove_service \
  --args '{"service_path": "/minimal-server"}'

# Toggle service state
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call \
  --tool toggle_service \
  --args '{"service_path": "/minimal-server"}'

# Health check all services
uv run cli/mcp_client.py --url http://localhost/mcpgw/mcp call --tool healthcheck --args '{}'

Tool Discovery and Invocation

# Find relevant tools
uv run cli/mcp_client.py call --tool intelligent_tool_finder \
  --args '{"natural_language_query": "get current time"}'

# Call a specific tool directly
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp call \
  --tool current_time_by_timezone \
  --args '{"tz_name": "Europe/London"}'

Troubleshooting

Common Issues

1. HTTP 403: Access forbidden

   • Check if your token has the required permissions
   • Verify the scopes.yml configuration includes the tool you're trying to access

2. HTTP 405: Method Not Allowed

   • Ensure the server path is correct
   • Verify the server is registered and running

3. Token Expired

   • Refresh your authentication token
   • For ingress tokens: Run the token refresh script
   • For M2M: Re-authenticate with credentials

4. Connection Refused

   • Check if the target server is running
   • Verify the proxy_pass_url in the service registration

Notes

• All service paths must start with '/'
• Tool arguments must be valid JSON
• The gateway URL defaults to http://localhost/mcpgw/mcp
• Direct server access bypasses the gateway and connects directly to the service