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¶

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
HTTP 405: Method Not Allowed
Ensure the server path is correct
Verify the server is registered and running
Token Expired
Refresh your authentication token
For ingress tokens: Run the token refresh script
For M2M: Re-authenticate with credentials
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