Skip to content

basic-usage.md

Latest commit

 

History

History
317 lines (254 loc) · 4.44 KB

basic-usage.md

File metadata and controls

317 lines (254 loc) · 4.44 KB

Basic Usage Examples

These examples show how to interact with the OpenSIPS MCP Server through an MCP client. Tool calls are shown in JSON format as they appear on the wire.

Health Check

Verify that OpenSIPS is running and reachable:

{
  "tool": "health_check",
  "arguments": {}
}

Expected response:

{
  "timestamp": 1745856000.0,
  "mi_reachable": true,
  "status": "healthy",
  "details": {
    "statistics": {
      "core:rcv_requests": 15234,
      "core:rcv_replies": 12891,
      "shmem:total_size": 67108864,
      "shmem:used_size": 4521984,
      "shmem:free_size": 62586880
    },
    "uptime": {
      "uptime": "3d 14h 22m 5s",
      "start_time": "Mon Apr 24 10:00:00 2026"
    }
  }
}

List MI Commands

Discover what MI commands are available on the connected instance:

{
  "tool": "mi_list_commands",
  "arguments": {}
}

Get Statistics

Retrieve memory statistics:

{
  "tool": "get_statistics",
  "arguments": {
    "group": "shmem"
  }
}

Get a specific statistic:

{
  "tool": "get_statistics",
  "arguments": {
    "group": "usrloc",
    "name": "registered_users"
  }
}

Subscriber Operations

List subscribers

{
  "tool": "subscriber_list",
  "arguments": {
    "domain": "example.com",
    "limit": 10
  }
}

Create a subscriber

{
  "tool": "subscriber_create",
  "arguments": {
    "username": "1001",
    "domain": "example.com",
    "password": "secure-password-123"
  }
}

Update a subscriber

{
  "tool": "subscriber_update",
  "arguments": {
    "id": 1,
    "password": "new-password-456"
  }
}

Delete a subscriber

{
  "tool": "subscriber_delete",
  "arguments": {
    "id": 1
  }
}

User Location

Show registered contacts for a user

{
  "tool": "ul_show_contacts",
  "arguments": {
    "aor": "1001@example.com"
  }
}

Expected response:

{
  "result": [
    {
      "contact": "sip:1001@10.0.0.50:5060;transport=udp",
      "expires": 3600,
      "q": 1.0,
      "callid": "abc123@10.0.0.50",
      "user_agent": "Ooma/3.0"
    }
  ]
}

Dump all registrations

{
  "tool": "ul_dump",
  "arguments": {
    "brief": true
  }
}

Dispatcher Operations

List dispatcher destinations

{
  "tool": "dispatcher_list_db",
  "arguments": {
    "setid": 1
  }
}

Add a destination

{
  "tool": "dispatcher_add",
  "arguments": {
    "setid": 1,
    "destination": "sip:10.0.0.20:5060",
    "weight": 50,
    "description": "Media server 4"
  }
}

Dialog Management

List active calls

{
  "tool": "dlg_list",
  "arguments": {}
}

End a specific call

{
  "tool": "dlg_end",
  "arguments": {
    "callid": "abc123@10.0.0.1",
    "from_tag": "ft-001",
    "to_tag": "tt-002"
  }
}

Diagnostics

Process list

{
  "tool": "get_process_list",
  "arguments": {}
}

Memory stats

{
  "tool": "get_memory_stats",
  "arguments": {}
}

Active TCP connections

{
  "tool": "get_tcp_connections",
  "arguments": {}
}

Security

Generate HA1 hash for a subscriber

{
  "tool": "security_generate_ha1",
  "arguments": {
    "username": "1001",
    "domain": "example.com",
    "password": "my-password"
  }
}

Expected response:

{
  "ha1": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "ha1b": "d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1"
}

List Pike-blocked IPs

{
  "tool": "pike_list_blocked",
  "arguments": {}
}

Unblock an IP

{
  "tool": "pike_unblock_ip",
  "arguments": {
    "ip": "203.0.113.50"
  }
}

Using Resources

Resources provide read-only system state. Access them by URI:

opensips://system/version     -> OpenSIPS version string
opensips://system/uptime      -> Server uptime
opensips://stats/all          -> All runtime statistics
opensips://db/subscribers     -> Subscriber table dump
opensips://modules/list       -> Module catalog
opensips://modules/dialog     -> Dialog module documentation
opensips://scenarios/list     -> Available deployment scenarios

Using Prompts

Prompts are guided workflows. Start one by name with arguments:

{
  "prompt": "troubleshoot_calls",
  "arguments": {
    "symptom": "Calls to external numbers get 503 Service Unavailable",
    "caller": "sip:1001@example.com"
  }
}

The prompt returns a structured analysis with steps to diagnose the issue, relevant tools to run, and potential fixes.