php-voip.ms/docs/mcp.md

Test MCP Server

This project includes a dependency-free HTTP JSON-RPC MCP endpoint for testing remote-agent access to the VoIP.ms library.

It is intended for development and testing. It binds to 0.0.0.0 by default, so use a firewall, VPN, or private network when exposing it beyond this machine.

Start The Server

cp .env-example .env
# Edit .env and optionally add MCP_AUTH_TOKEN='choose-a-long-random-token'

./bin/serve-mcp.sh

The launcher reads the project-root .env file when present. Already exported environment variables take precedence over .env values.

Defaults:

MCP_HOST=0.0.0.0
MCP_PORT=8787
MCP endpoint: http://0.0.0.0:8787/mcp
Health endpoint: http://0.0.0.0:8787/health

If MCP_AUTH_TOKEN is not set, the launcher generates one for that session. For local unauthenticated testing only:

MCP_ALLOW_UNAUTHENTICATED=1 ./bin/serve-mcp.sh

The preferred authentication form is:

Authorization: Bearer <MCP_AUTH_TOKEN>

For clients that cannot send custom headers during testing, the same token can be passed as a query parameter:

http://your-host:8787/mcp?token=<MCP_AUTH_TOKEN>

Prefer the Authorization header when the client supports it.

Smoke Test

curl -s http://127.0.0.1:8787/health

Initialize:

curl -s http://127.0.0.1:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"test"}}}'

Streamable HTTP GET probe:

curl -sN http://127.0.0.1:8787/mcp \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN"

Legacy SSE probe:

curl -sN http://127.0.0.1:8787/sse \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN"

List tools:

curl -s http://127.0.0.1:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call a safe dry-run mutation:

curl -s http://127.0.0.1:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"voipms_add_number_to_phonebook_group","arguments":{"number":"5553334444","group_name":"Spam","dry_run":true}}}'

Exposed Tools

• voipms_get_balance
• voipms_get_phonebook_groups
• voipms_get_phonebook_entries
• voipms_get_callerid_filters
• voipms_get_accounts
• voipms_get_call_accounts
• voipms_get_call_recordings
• voipms_get_call_recording
• voipms_send_call_recording_email
• voipms_get_call_transcript
• voipms_get_recent_cdr
• voipms_add_number_to_phonebook_group
• voipms_remove_number_from_phonebook_group

Mutation tools default to dry_run=true and must be called with dry_run=false to apply changes.

voipms_get_call_transcript is currently a placeholder. It is listed so remote agents can discover that transcripts are planned, but transcription storage/provider support has not been implemented yet.

voipms_get_accounts is a friendly alias for voipms_get_call_accounts. These tools return account filter values for CDR and call recording tools. They do not list VoIP.ms portal login users. Use the returned value field as the account argument.