Zelinqa MCP

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

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.

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. zelinqa_adjust and zelinqa_add_context can replace the pending question, for example when the information it asked for is now known: always ask the question they return. The full answering rules are in docs/operations.md.

Tools

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.

zelinqa-mcp --advanced swaps the business tools for six low-level ones that expose API identifiers and full state. See docs/operations.md.

Configuration

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_status and 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.