MCP Server Command

Run an MCP server exposing A2A capabilities as tools

The mcp command starts a Model Context Protocol (MCP) server that exposes Handler’s A2A functionality as MCP tools and resources. This allows MCP-compatible clients like Claude Desktop, Cursor, and other AI assistants to interact with A2A agents.

handler mcp [OPTIONS]

Options

--transport · string · default: "stdio"

Transport protocol to use. Options: stdio, sse, streamable-http. Default: stdio

Short form: -t

Transport Types

• stdio: Standard input/output (recommended for most MCP clients)
• sse: Server-Sent Events
• streamable-http: HTTP streaming

Examples

Start MCP server (stdio)

handler mcp

Available Tools

The MCP server exposes the following categories of tools:

Card Tools

validate_agent_card · tool

Validate an agent card from URL or file

Parameters:

• source (string): URL or file path to validate

get_agent_card · tool

Retrieve an agent’s full card details

Parameters:

• agent_url (string): Agent URL
• authenticated (boolean, optional): Request authenticated card

Message Tools

send_message · tool

Send messages to agents with session and auth support

Parameters:

• agent_url (string): Agent URL
• text (string): Message text
• stream (boolean, optional): Enable streaming
• context_id (string, optional): Context ID
• task_id (string, optional): Task ID
• use_session (boolean, optional): Continue from saved session
• push_url (string, optional): Webhook URL
• push_token (string, optional): Webhook token
• bearer_token (string, optional): Bearer auth
• api_key (string, optional): API key auth

Task Tools

get_task · tool

Get task status and details

Parameters:

• agent_url (string): Agent URL
• task_id (string): Task ID
• history_length (integer, optional): Number of history messages
• bearer_token (string, optional): Bearer auth
• api_key (string, optional): API key auth

cancel_task · tool

Cancel a running task

Parameters:

• agent_url (string): Agent URL
• task_id (string): Task ID
• bearer_token (string, optional): Bearer auth
• api_key (string, optional): API key auth

set_task_notification · tool

Configure push notification webhooks

Parameters:

• agent_url (string): Agent URL
• task_id (string): Task ID
• url (string): Webhook URL
• token (string, optional): Webhook token
• bearer_token (string, optional): Bearer auth
• api_key (string, optional): API key auth

get_task_notification · tool

Get push notification config

Parameters:

• agent_url (string): Agent URL
• task_id (string): Task ID
• config_id (string, optional): Config ID
• bearer_token (string, optional): Bearer auth
• api_key (string, optional): API key auth

Session Tools

list_sessions · tool

List all saved sessions

Parameters: None

get_session_info · tool

Get session for a specific agent

Parameters:

• agent_url (string): Agent URL

clear_session_data · tool

Clear saved session state

Parameters:

• agent_url (string, optional): Agent URL (omit to clear all)

Auth Tools

set_agent_credentials · tool

Save bearer token or API key for an agent

Parameters:

• agent_url (string): Agent URL
• bearer_token (string, optional): Bearer token
• api_key (string, optional): API key
• api_key_header (string, optional): Header name for API key (default: X-API-Key)

clear_agent_credentials · tool

Remove saved credentials

Parameters:

• agent_url (string): Agent URL

MCP Client Configuration

Claude Desktop

Add Handler to your Claude Desktop configuration (claude_desktop_config.json):

claude_desktop_config.json

{
  "mcpServers": {
    "handler": {
      "command": "handler",
      "args": ["mcp"]
    }
  }
}

Configuration File Locations

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Custom Transport

To use a different transport:

claude_desktop_config.json

{
  "mcpServers": {
    "handler": {
      "command": "handler",
      "args": ["mcp", "--transport", "sse"]
    }
  }
}

Usage in MCP Clients

Once configured, you can interact with A2A agents through your MCP client:

Example prompts in Claude Desktop:

• “Use the send_message tool to ask the agent at http://localhost:8000 what the weather is like”
• “Get the agent card from http://localhost:8000”
• “List all my saved sessions”
• “Cancel task task_abc123 at http://localhost:8000”
• “Set credentials for http://localhost:8000 with bearer token xyz”

The MCP server allows AI assistants to autonomously interact with A2A agents, making it easy to integrate A2A workflows into your AI-assisted development.

The MCP server uses Handler’s session and credential management, so sessions and credentials set through MCP tools are shared with CLI commands and vice versa.

Debugging

To debug MCP server issues:

1. Check Claude Desktop logs (Help → Developer Tools)
2. Verify Handler is installed and accessible in your PATH
3. Test the command manually: handler mcp should start without errors
4. Check permissions on the configuration file

The MCP server runs as a separate process. Credentials and sessions are persisted to ~/.handler/ and shared across all Handler interfaces (CLI, TUI, MCP).