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.
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.
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.
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 |
|---|---|
claude mcp add zelinqa \
-e ZELINQA_API_KEY=YOUR_RUNTIME_API_KEY \
-- uvx zelinqa-mcp |
{
"mcpServers": {
"zelinqa": {
"command": "uvx",
"args": ["zelinqa-mcp"],
"env": {
"ZELINQA_API_KEY": "YOUR_RUNTIME_API_KEY"
}
}
}
} |
Codex (~/.codex/config.toml) |
From a checkout |
[mcp_servers.zelinqa]
command = "uvx"
args = ["zelinqa-mcp"]
env = { ZELINQA_API_KEY = "YOUR_RUNTIME_API_KEY" } |
git clone https://github.com/Zelinqa/zelinqa-mcp.git
cd zelinqa-mcp
uv sync --group dev --locked
uv run zelinqa-mcp --version |
Ready-to-copy files for each host are in examples/. Keep your host's tool-approval policy: some calls create sessions and feedback.
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.
| 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.
| 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 |
- 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.
- 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.
Apache-2.0. Release steps are in RELEASING.md.