Limitations and anti-patterns

April 28, 2026 · View on GitHub

Where this project is genuinely useful — and where it is not. Read this before you bet a production deployment on it.

The project's goal is to make every common OpenSIPS task accessible through structured tools and narrative documentation. That goal does not extend infinitely. Some things this project does not (and will not) do, and some uses for which it is the wrong choice.

What this project is

A configuration / operations / observability layer that wraps the real OpenSIPS proxy. It is not a replacement for OpenSIPS itself. OpenSIPS still does the SIP work; this project gives you better tools to drive it.

The two interfaces:

  1. MCP server — the LLM-facing interface. cfg_generate, cdr_audit, cluster_drain_node, etc. are exposed as MCP tools any compatible client (Claude Desktop, Cursor, Cline, Continue, ...) can call.
  2. CLI — the same primitives exposed as opensips-mcp cfg ... subcommands so a shell script, Ansible playbook, or operator familiar with kubectl-style tools can drive them without any LLM in the loop.

Hard limitations

The MCP path requires an LLM client to be useful in conversational mode.

cfg_generate is callable as a tool, but discovering which tool to call (vs. the other 221) is the LLM's job. Without an LLM, you'll fall back to the CLI, which has good ergonomics but does not match the "describe the problem, get a solution" flow.

Workaround: use the CLI directly when scripting; use the MCP when exploring or troubleshooting interactively.

The cfg engine produces config; it does not run OpenSIPS.

cfg_generate writes a file. cfg_validate invokes opensips -C on the rendered file. Neither starts, restarts, or reloads OpenSIPS. Deployment is your job — Docker, systemd, Kubernetes, whatever.

Why: restarting OpenSIPS in production is a privileged operation with operational consequences (call drops if not done via drain), and binding it to an LLM tool would create incident-causing capability that nobody asked for.

LLM tool calls are not deterministic.

Two LLM clients given the same English description may pick different tool sequences, supply slightly different parameters, and produce non-identical configs. The configs that DO get produced are validated by the linter and by opensips -C, but the path to them is not reproducible.

Workaround: for production change-management, use the CLI directly or a Makefile / Ansible task that calls the CLI. Treat the MCP path as exploratory / supportive rather than the source of truth.

The IMS Cx scenario is structurally correct but not interop-tested in your environment.

We verified function signatures against opensips.org docs and the 3GPP TS 29.229 command codes / AVPs. We provided an end-to-end runbook against open5gs HSS. We did not test against a commercial HSS, regulator-mandated AVP profiles, or your specific operator environment. The runbook makes this explicit; the scenario file does too.

Workaround: treat IMS Cx as advisory until you've completed the open5gs interop test in your lab. Layer on additional dictionary entries for vendor-specific AVPs your HSS expects.

MSRP / Diameter / IMS support is partial by design.

msrp_gateway, radius_auth, ims_cx_scscf, and qos_routing exist as scenario templates but the long tail of MSRP relay behaviours / Diameter dictionary edge cases / IMS deployment quirks will never be fully covered by a single tool. These scenarios get you started; they don't replace operator-specific tuning.

Some scenarios deliberately leave anti-flood as an operator decision.

b2bua, call_center, load_balancer, registrar_class5, residential_pbx, webrtc_gateway ship without pike loaded by default. The lint rule OPS011 fires on these as a warning, which is the intent — anti-flood is right for public-facing deployments and overkill on trusted-LAN ones, and the operator gets to choose.

Anti-patterns — things you should NOT do with this

Use the LLM tools to bypass code review.

The MCP makes it tempting to "ask Claude to fix the dialplan and push it to prod." Don't. Generated configs go through the same review as hand-written ones. Use cfg_diff and cfg_diff_reference so the review is mechanical.

Treat cfg_validate as the only gate.

opensips -C checks syntax. It does not catch:

  • Wrong but parseable values (db_url pointing at the wrong host).
  • Logic errors (a routing rule that loops).
  • Performance regressions (children=2 on a 32-core box).

The linter's 20+ semantic rules catch some of the second class. Smoke-tests catch some of the third. Production traffic catches the rest. Treat the validation pipeline as necessary but not sufficient.

Run the MCP server on a non-loopback interface without a reverse proxy.

The server refuses to start if you try this without explicit OPENSIPS_MCP_BEHIND_PROXY=true. Don't override the refusal unless you have actually deployed nginx / traefik in front to enforce auth. FastMCP does not natively check OPENSIPS_MCP_API_KEY on incoming SSE / streamable-http requests.

Use the LLM for high-CPS routing decisions.

Tools like cfg_explain, troubleshoot_calls, security_audit are advisory. They run at human conversational latency. Do not embed an LLM call in the SIP routing hot path. OpenSIPS' own drouting / dispatcher / qrouting modules make microsecond decisions; an LLM round-trip is several orders of magnitude slower and not subject to SIP retransmit semantics.

Trust capacity numbers from cfg_tune without measurement.

The tuner emits a warning whenever the default 2 KB/dialog heuristic is used because that under-allocates 2-4× for any real deployment using $dlg_val, topology_hiding, B2BUA legs, or siprec. Measure your actual per-dialog footprint before sizing shared memory; pass dlg_size_bytes explicitly. The default is a starting point, not a bet-the-deployment number.

Use the project as a substitute for OpenSIPS expertise.

The project lowers the cost of the common path. The uncommon path — debugging a niche carrier interop bug, building a custom module, doing performance forensics on a 100k-CPS deployment — is still an expert problem. The narrative docs, prompts, and CLI help you get further faster, but they don't substitute for understanding SIP / OpenSIPS internals.

When this project is the WRONG choice

You need a managed SIP service, not a tool to run your own.

If "I want to make phone calls" is your goal and you have no desire to operate SIP infrastructure, use Twilio / Telnyx / Bandwidth / Vonage / Plivo / SignalWire. They have SLAs, regulatory compliance built in, and 24/7 support. This project assumes you want to run your own proxy and need help doing it well.

You're an Asterisk shop and only need PBX features.

Asterisk + FreePBX is the right choice for "I need an office PBX with IVR, voicemail, call queues." OpenSIPS is the wrong tool for that — it's a proxy, not an application server. The asterisk_trunking scenario fronts an Asterisk box with OpenSIPS when you need scale + perimeter security; if you only need Asterisk, just run Asterisk.

You need a SIP load balancer that supports HTTP/2 / gRPC / arbitrary protocols.

OpenSIPS speaks SIP, MSRP, and a few related protocols. It does not speak HTTP/2, gRPC, MQTT, etc. For multi-protocol L7 load balancing, use HAProxy / Envoy / Caddy.

Your team can't take an LLM dependency for any reason.

The MCP path requires an LLM client somewhere. The CLI does not. But documentation, prompts, and the conversational discovery experience — the things that lower the OpenSIPS learning curve the most — assume an LLM. If your team genuinely cannot use one, this project still has value via the CLI, but a good fraction of its design is wasted on you.

You need certified telecom-equipment status.

OpenSIPS is software; this project is software around it. Neither is certified for any regulatory regime per se. Operators who need "Network Equipment Building System (NEBS) Level 3" or similar certifications need to do their own.

Where the project is the right choice

To balance the above:

  • You're standing up a new OpenSIPS deployment and want a working config for one of 21 common patterns in 5 minutes.
  • You're upgrading from an older OpenSIPS and don't want to read 8 upgrade notes — cfg_migrate_plan does it for you.
  • You're an existing Kamailio shop curious whether OpenSIPS would be easier to ship with — see kamailio-vs-opensips.md.
  • You inherited a 1500-line opensips.cfg from someone who left and need to understand it line by line — cfg_explain, cfg_lint, cfg_diff_reference.
  • You're an OpenSIPS pro who wants the cfg engine + linter as shell-callable tools but doesn't want LLM in your CI — the CLI is for you.
  • You operate in production and need post-deploy smoke tests, drift snapshots, cluster drain procedures with confirmation — see the operator runbooks under docs/learn/.
  • You're explaining SIP / OpenSIPS to a colleague and want a single read-this-first link — docs/learn/sip-in-10-minutes.md.

If you read all of the above and the project still fits your problem, you're in the right place. If it doesn't, that's also an honest answer and we'd rather you find this page early than at the end of a frustrating week.