FAQ & Troubleshooting

April 28, 2026 · View on GitHub

Common questions and setup problems for the OpenSIPS MCP Server.

Setup & connectivity

Claude doesn't see any OpenSIPS tools

  1. Restart the MCP client after editing its config (Claude Desktop, Cursor, Continue don't auto-reload).
  2. Check the client's MCP server list. In Claude Desktop, it's the hammer icon.
  3. Run the server manually with opensips-mcp --transport stdio — if it errors out in your terminal, the same error is silently killing the client's launch.
  4. On Windows, use full paths in the client config; PATH isn't inherited the same way.

mi_reachable: false

The server is running but can't reach OpenSIPS's MI endpoint.

  • Confirm MI_URL in .env matches your OpenSIPS deployment.
  • The OpenSIPS config must load either mi_http, mi_datagram, or mi_fifo. This server talks HTTP by default.
  • Test directly: curl -X POST http://<host>:<port>/mi -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"ps","id":1}'

"Permission denied: role 'readonly' lacks '...'"

The server runs as readonly by default. For any mutating tool (create, update, delete, reload), set ROLE=admin in .env. For production, use a reverse proxy that sets the role per-request based on the caller's API key.

"Unknown MI command"

The tool is wrapping an MI command that doesn't exist on your OpenSIPS build (either because the module isn't loaded or the version doesn't support it).

  • Call mi_list_commands — returns what the live instance actually supports.
  • Load the relevant module in opensips.cfg (loadmodule "foo.so").

Docker

docker compose up fails

  • Ensure Docker 20+ and docker compose plugin (not legacy docker-compose).
  • Free ports 5060/udp, 5061/udp, 5060/tcp, 8888 (MI), 3306 (MySQL), 8700 (MCP).
  • If you see Error response from daemon: Ports are not available, another SIP proxy (Kamailio? Asterisk?) is already listening.

Containers are unhealthy

docker compose -f docker/docker-compose.yml ps
docker compose -f docker/docker-compose.yml logs opensips

Ninety percent of the time it's a DB connection failure — the MySQL container wasn't ready before OpenSIPS started. docker compose restart opensips usually fixes it; for a permanent fix, make sure depends_on.condition: service_healthy is set.

Config generation

Generated config won't start

Always run in this order:

  1. cfg_validate — syntax
  2. cfg_lint — semantic rules
  3. cfg_explain_route — sanity-check route blocks

If cfg_validate passes but OpenSIPS errors at boot, the most common causes:

  • Missing loadmodule for a function you used
  • DB URL pointing at the wrong host (Docker: use service name, not localhost)
  • Port already in use (another SIP proxy running)
  • UDP socket permission (low ports need cap_net_bind_service or root)

"I asked for X and Claude keeps generating Y"

Be explicit about scenarios and versions:

Generate a residential-auth scenario for OpenSIPS 3.5 with MySQL auth and nathelper.

If the scenario doesn't exist, call cfg_list_scenarios first and pick one by name. For non-standard combinations, use cfg_compose_flags + cfg_build_from_flags (Kamailio-style WITH_* flags).

Runtime behaviour

Calls are failing — what do I run first?

Use the opensips-troubleshoot skill or ask:

Run a quick diagnostic — health, dialogs, dispatcher state, recent SL/TM stats. Flag anything unusual.

Claude will chain:

  • health_check
  • dlg_list
  • get_statistics (sl, tm, core)
  • dispatcher_list_db / lb_list
  • pike_list_blocked
  • Recent docker_logs if containerised

One-way audio

Almost always a NAT/media issue. Check:

  1. rtpengine_show — is RTPEngine allocating ports?
  2. Nathelper modparams — is fix_nated_sdp being called?
  3. Firewall — is the RTP port range (typically 10000-20000/udp) open?

The opensips-troubleshoot skill has a full media branch.

Migrations

"Which version should I migrate to?"

  • 3.4 is the long-term-support branch.
  • 3.5 / 3.6 are production-quality.
  • 3.7 / 4.0 are current/edge — safe for new deployments, review migration notes for existing ones.
  • Skip no hops: 2.4 → 4.0 goes through every minor version in between.

"Claude wants to apply the migration — is it safe?"

The opensips-migrator subagent refuses to apply a migration without an explicit acknowledgement of silent-behaviour findings. Always:

  1. Backup the original config.
  2. Review the full plan.
  3. Apply in dev/staging first.
  4. Use cfg_diff to review the result before deploying to prod.

Security

"Should I run this on a public IP?"

Not without an auth proxy. The server has an API key setting but does not enforce it at the transport layer for SSE/streamable-http. Use a reverse proxy (nginx config provided in docker/nginx/) to validate the Authorization: Bearer header.

Role separation

RoleUse for
readonlyDashboards, alerts, inspection-only automations
adminConfig generation, runtime mutations, CRUD on DB tables

Set via ROLE= in .env or per-request via proxy.

Learning SIP / OpenSIPS

"I'm new to SIP — where do I start?"

Use the opensips-teacher subagent, or these prompts:

  • teach_concept — any topic
  • explain_sip_ladder — paste a SIP trace, get an ASCII ladder + analysis
  • explain_route — paste a route block, get a line-by-line walkthrough
  • debug_sip_message — paste a raw SIP message, get it parsed + explained

The opensips://docs/guide/sip-101 and opensips://docs/guide/quickstart resources are also good primers.

"The generated config uses features I don't understand"

Call cfg_explain with the directive/function name, or cfg_explain_route for a whole route. Both work offline — no running OpenSIPS needed.

Feature requests / reporting bugs

File issues at https://github.com/OFFICERINGLLC/opensips-mcp-server/issues

Include:

  • OpenSIPS version (get_statistics group=core shows it)
  • MCP server version (python -m opensips_mcp --version)
  • What tool you called and what you expected vs got