Asterisk S2S

You can run an MCP server that connects an automated conversational workflow to Asterisk S2S and manage phone calls through a simple MCP client. This setup lets you initiate reminders, confirmations, and surveys over the phone with real-time speech-to-speech interactions, while keeping control over call status, history, and results.

How to use

You will use an MCP client to send high-level intents like starting a call to remind a user about an appointment. The MCP server handles dialing through the Asterisk back end and coordinates real-time speech-to-speech interaction during the call. You can check the latest call status, retrieve the last result, and review call history after each conversation.

Typical usage patterns include: initiating a call to a contact with a clear purpose, waiting for the response, and then saving the outcome (such as confirmation or rescheduling). You can also review ongoing calls, monitor system health, and access logs or metrics for troubleshooting and optimization.

How to install

Prerequisites: Node.js 18 or newer, npm or pnpm, and a basic MCP client environment prepared to run MCP servers.

Option 1: NPX (recommended) — run this single command to start using the MCP server directly.

npx @grec0/mcp-s2s-asterisk@latest

Option 2: Global installation — install the package globally and start the server via its CLI.

npm install -g @grec0/mcp-s2s-asterisk
mcp-s2s-asterisk

Configuration and runtime notes

Set up environment variables that the server uses to connect to the Asterisk-based phone service and to receive results callbacks.

# 🌐 Asterisk API URL
export PHONE_API_URL="http://192.168.4.44:8000"

# 🔑 Authentication key
export PHONE_API_KEY="api-key"

# 🔄 Callback URL for results
export MCP_CALLBACK_URL="http://localhost:3000"

Configure the MCP client to include the MCP server using the stdio (local) runtime command as shown in the example configuration.

{
  "mcpServers": {
    "asterisk_s2s": {
      "command": "npx",
      "args": ["@grec0/mcp-s2s-asterisk@latest"],
      "env": {
        "PHONE_API_URL": "http://192.168.4.44:8000",
        "PHONE_API_KEY": "api-key",
        "MCP_CALLBACK_URL": "http://localhost:3000"
      }
    }
  }
}

Security & compliance

Authentication is secured via an API key. All communications are encrypted in transit with TLS/SSL. Call data is audited through logs, and you can manage privacy with local processing and GDPR-focused practices.

Troubleshooting and tips

If you encounter issues with call initiation or status updates, verify the MCU callback URL is reachable, the API key is correct, and the Asterisk API URL is available. Check the MCP client configuration to ensure environment variables are passed to the MCP server process.

Notes and examples

You can monitor health, metrics, and logs to understand performance and reliability. Example use cases include appointment reminders, booking confirmations, customer follow-ups, and automated surveys.

Appendix: Tools and endpoints

The server exposes tools to perform calls, monitor status, access history, and inspect metrics and logs. See the dedicated tool references for the exact function names and descriptions in your MCP client environment.

Available tools

phone_make_call

Initiate a phone call through the Asterisk-based MCP server with a defined purpose, such as reminders or confirmations.

phone_get_status

Retrieve the current status of an ongoing or completed call.

phone_cancel_call

Cancel an active or scheduled call.

phone_get_active_calls

List all calls that are currently active.

phone_health_check

Check the overall health of the MCP server and its integration points.

phone_get_metrics

Retrieve performance metrics for monitoring and optimization.

phone_get_logs

Fetch detailed logs for auditing and troubleshooting.

phone_get_conversation_history

Access past conversation records and transcripts.

phone_get_last_result

Obtain the result of the most recent call.