hold-slayer/docs/mcp-server.md

MCP Server

The MCP (Model Context Protocol) server lets any MCP-compatible AI assistant control the Hold Slayer gateway. Built with FastMCP, it exposes tools and resources over SSE.

Overview

An AI assistant connects via SSE to the MCP server and gains access to tools for placing calls, checking status, sending DTMF, getting transcripts, and managing call flows. The assistant can orchestrate an entire call through natural language.

Tools

make_call

Place an outbound call through the SIP trunk.

Param	Type	Required	Description
number	string	Yes	Phone number to call (E.164 format)
mode	string	No	Call mode: direct, hold_slayer, ai_assisted (default: hold_slayer)
intent	string	No	What you want to accomplish on the call
call_flow_id	string	No	ID of a stored call flow to follow

Returns: Call ID and initial status.

end_call

Hang up an active call.

Param	Type	Required	Description
call_id	string	Yes	The call to hang up

send_dtmf

Send touch-tone digits to an active call (for manual IVR navigation).

Param	Type	Required	Description
call_id	string	Yes	The call to send digits to
digits	string	Yes	DTMF digits to send (e.g., "1", "3#", "1234")

get_call_status

Check the current state of a call.

Param	Type	Required	Description
call_id	string	Yes	The call to check

Returns: Status, duration, hold time, audio classification, transcript excerpt.

get_call_transcript

Get the live transcript of a call.

Param	Type	Required	Description
call_id	string	Yes	The call to get transcript for

Returns: Array of transcript chunks with timestamps and speaker labels.

get_call_recording

Get recording metadata and file path for a call.

Param	Type	Required	Description
call_id	string	Yes	The call to get recording for

Returns: Recording path, duration, file size.

list_active_calls

List all calls currently in progress. No parameters.

Returns: Array of active calls with status, number, duration.

get_call_summary

Get analytics summary — hold times, success rates, call volume. No parameters.

Returns: Aggregate statistics across all calls.

search_call_history

Search past calls by number, company, or date range.

Param	Type	Required	Description
query	string	Yes	Search term (phone number, company name)
limit	int	No	Max results (default: 20)

learn_call_flow

Build a reusable call flow from a completed exploration call.

Param	Type	Required	Description
call_id	string	Yes	The exploration call to learn from
company	string	No	Company name for the flow

Returns: The generated CallFlow object.

Resources

MCP resources provide read-only data that assistants can reference:

Resource URI	Description
gateway://status	Current gateway status — trunk registration, active calls, service health
gateway://calls	List of all active calls with current status
gateway://calls/{call_id}	Detailed status for a specific call
gateway://flows	List of all stored call flows
gateway://analytics	Call analytics summary

Configuration

The MCP server is mounted on the FastAPI app at /mcp.

Connecting an AI Assistant

Add to your MCP client configuration (e.g., Claude Desktop, Cline):

{
  "mcpServers": {
    "hold-slayer": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

Example Conversation

Here is how an AI assistant would use the MCP tools to handle a complete call:

User: "Call Chase Bank and dispute the Amazon charge from December 15th"

Assistant actions:

1. Calls make_call(number="+18005551234", mode="hold_slayer", intent="dispute Amazon charge Dec 15th", call_flow_id="chase-bank-main")
2. Receives call_id: "call_abc123"
3. Polls get_call_status("call_abc123") periodically
4. Status progression: trying → ringing → connected → on_hold
5. Tells user: "I'm on hold with Chase Bank. Currently 4 minutes in. I'll let you know when someone picks up."
6. Status changes to transferring — human detected!
7. Tells user: "A live agent just picked up. I'm transferring the call to your desk phone now. Pick up!"
8. After the call, calls learn_call_flow("call_abc123", company="Chase Bank") to save the IVR path for next time.

User: "How long was I on hold?"

Assistant actions:

1. Calls get_call_summary()
2. Reports: "Your Chase Bank call lasted 12 minutes total, with 8 minutes on hold. The disputes department averages 6 minutes hold time on Tuesdays."