Install · Example · Tools · Configuration · Operations · Français
Your assistant handles the conversation. Zelinqa decides what to ask next. Describe once, in Zelinqa Studio, what a conversation must find out. This server gives any MCP host the tools to run that conversation: start it, pass each reply, get the next question, record the result. The model only ever sees question text, choice labels and a conversation name. Session, decision and state identifiers stay inside the server.
Fewer tokens, deterministic, explainable
The engine chooses the questions, so the model stops generating them and stops re-asking: fewer tokens for the same dialogue. The choice itself is a selection over your published domain, not a generation: the same state always yields the same question, and each decision carries what the question collects, the progress of every dimension and an explicit stop reason, so a conversation can be audited after the fact. Token figures: internal test bench, September 2026: more than 700 conversations replayed twice with the same assistant, alone then steered by the Zelinqa engine, with simulated respondents replayed identically on both sides. Protocol, figures and limits: read the test bench report. A scientific benchmark with shared data and code is planned before the end of 2026.
Why
Any assistant that has to ask before it decides, for an interview, a qualification, an orientation, a triage or a recommendation, improvises its questions and decides with gaps. With this server, the engine runs the questioning phase from your published domain and the model decides once, with a complete, typed state.
Install
You need Python 3.11+ with uv, and a runtime API key for a published domain, created in Zelinqa Studio. A free Developer edition account is enough.
Or add the server to your host by hand. The command is the same everywhere: uvx zelinqa-mcp, with the key in the host's secret environment.
| Claude Code | Claude Desktop · Cursor · Windsurf |
|---|---|
|
|
Codex (~/.codex/config.toml) | From a checkout |
|
|
Ready-to-copy files for each host are in examples/. Keep your host's tool-approval policy: some calls create sessions and feedback.
A conversation in four tool calls
The model calls zelinqa_start, asks the returned question in its own words, passes the person's reply to zelinqa_next_question, and repeats until the engine stops. At the end it records what really happened.
▶ zelinqa_start {"conversation": "lead-42"}
◀ ask · "Which budget range are you considering this year?"
choices: Under €10k · €10k to €50k · Over €50k
▶ zelinqa_next_question {"conversation": "lead-42", "choice_labels": ["€10k to €50k"]}
◀ ask · "When would you like to start?"
progress: budget covered · timeline not started
▶ zelinqa_next_question {"conversation": "lead-42", "user_text": "Next quarter, after the sales kickoff."}
◀ stop · objective achieved
▶ zelinqa_feedback {"conversation": "lead-42", "result": "success"}
Calling zelinqa_next_question without a reply only redisplays the pending question. When a CRM already knows an answer, zelinqa_adjust records it without asking. The full answering rules are in docs/operations.md.
Tools
| Tool | What it does |
|---|---|
zelinqa_start | Start or recover a named conversation and return its first or pending question |
zelinqa_next_question | Record the person's reply and return the next question; without a reply, redisplay the pending question without a new turn |
zelinqa_add_context | Add a context summary without asking a question |
zelinqa_adjust | Apply confirmed data, dimension statuses or an objective override without consuming a turn |
zelinqa_status | Refresh progress and the pending question |
zelinqa_feedback | Record an observed business result: success, partial or failure |
zelinqa_forget | Free the local handle; does not delete API data |
Results carry question text, ranks, choice labels, objective progress and counters; next-decision results add warnings, the stop reason and degraded-mode reasons. At max_turns the result has action: "stop" and stop_reason: "max_turns_reached", and later calls return the same stop. Reaching the turn limit is not proof that the objective was achieved.
| Also available | Purpose |
|---|---|
Resource zelinqa://guide | The same guide supplied as the server's instructions |
Prompt zelinqa_integration_check | User-selected integration test checklist |
Skill zelinqa | Short workflow for hosts that support skills; copy the directory into your host's skills folder |
zelinqa-mcp --advanced swaps the business tools for six low-level ones that expose API identifiers and full state. See docs/operations.md.
Configuration
| Environment variable | Purpose |
|---|---|
ZELINQA_API_KEY | Required runtime key, scoped to one published domain |
ZELINQA_BASE_URL | Default https://api.zelinqa.ai |
ZELINQA_TIMEOUT_SECONDS | Per-attempt timeout, default 30 seconds |
ZELINQA_MAX_RETRIES | Retry count, default 2 |
ZELINQA_SESSION_ID | Optional host-owned session to resume after restart |
ZELINQA_CONVERSATION | Local name of that resumed session; default conversation |
Security and state
- Transport is stdio, one isolated process per trusted host and user. HTTP hosting is disabled until authentication and session isolation exist. Logs go to stderr; stdout is reserved for MCP.
- The server holds at most 128 named conversations in memory and never evicts one silently. Names are process-local: to survive a restart, the host keeps the API session id and injects the resume variables above, outside the model.
- Calls that mutate the same conversation must be sequential; a simultaneous call is rejected rather than answered with stale state. After a conflict, call
zelinqa_statusand reconcile before answering again.
Details, retry semantics and the test suites: docs/operations.md. Vulnerability reports: SECURITY.md.
Related
- zelinqa-sdk: the Python and TypeScript clients this server is built on, for applications that call the API directly.
- docs.zelinqa.ai: concepts, Studio guide and API reference.
License
Apache-2.0. Release steps are in RELEASING.md.