Zelinqa MCP Server

Zelinqa MCP

The official MCP adapter for goal-oriented question selection. The model handles the conversation; the SDK handles session IDs, pending decisions and state versions.

Python 3.11+ required. Release prerequisites are in PUBLISHING.md.

MCP host → zelinqa-mcp → Python SDK zelinqa → api.zelinqa.ai

Start

Run the published package:

uvx zelinqa-mcp

To run from source:

git clone https://github.com/Zelinqa/zelinqa-mcp.git
cd zelinqa-mcp
uv sync --group dev --locked
uv run zelinqa-mcp --version

Configure ZELINQA_API_KEY in the host's secret environment (runtime scope). Never paste keys into a chat, repository or report. Host examples are in examples/; replace local checkout paths where necessary.

The supported transport is stdio, one isolated process per trusted host/user. HTTP hosting is disabled pending authentication and session isolation. Logs use stderr; stdout is reserved for MCP. Do not share one process across untrusted users.

Business tools (default)

The seven business tools use this loop: start, ask the returned question, then pass the person's reply to zelinqa_next_question. Repeat until stopped or the objective is achieved, then report the real business result with zelinqa_feedback.

Example tool sequence (the second call only redisplays the pending question):

{"tool":"zelinqa_start","arguments":{"conversation":"demo-42"}}
{"tool":"zelinqa_next_question","arguments":{"conversation":"demo-42"}}
{"tool":"zelinqa_next_question","arguments":{"conversation":"demo-42","user_text":"For my living room"}}

For a displayed choice use choice_labels: ["Contemporary"]. Use candidate_rank when asking a candidate other than rank 1. Session, decision and question IDs, as well as state versions, are not tool inputs. An open question requires the person's words in user_text. An outcome alone is accepted only for refused or asked_no_answer, for any question type. Closed and semi-open questions accept exact choice_labels; semi-open choices can also include free_text. assistant_text records the wording actually asked. Never invent an answer or outcome. A reply with no pending question is an error. Invalid local answers leave the pending question unchanged and can be corrected without an API call. Calling without reply fields only redisplays the pending question; candidate_rank defaults to 1.

When a CRM already knows an answer, use zelinqa_adjust instead of asking again. It accepts dimensions: [{"id":"configured_dimension_id","status":"excluded"}], data: [{"id":"configured_information_id","value":2500}], or objective: "not_achieved". Dimension statuses are achieved, not_achieved, and excluded; data also supports operation: "unset" and operation: "not_applicable" without a value. These are configured business IDs, not session or decision IDs. Use only verified information; adjust does not consume a turn and returns the usual business view. After a conflict, call status and reconcile before retrying. A question already pending is not recalculated by adjust; inspect the returned view and prefer adjusting before next_question.

Results include question text, ranks, choice labels, objective progress and counters. Next-decision results also include warnings, stop reason and degraded-mode reasons. The full target/ID maps are deliberately absent. 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 of objective completion.

State, retries and memory

• The registry holds at most 128 conversations. It never silently evicts one; use forget when finished. It stores current state, not a conversation transcript.
• Calls mutating the same conversation must be sequential. A simultaneous call is rejected, not queued with a stale answer. Different conversations stay separate.
• The SDK reuses one idempotency key across retries of a single HTTP mutation. Repeating a tool call manually is a new operation, not an automatic replay.
• On a conflict or interrupted request, call zelinqa_status and reconcile with the pending question before answering again. Errors are not hidden.
• Names are process-local. For restart persistence the host must retain the API session ID and inject the resume variables above outside the model.

zelinqa-mcp --advanced exposes the six low-level tools instead: create_session, resume_session, next, apply_events, get_session, submit_feedback (all prefixed zelinqa_). This mode intentionally exposes API identifiers and full state. Configuration management is not a MCP tool: use the SDK's separate configuration client/scopes.

Prompts, resource and skill

Reading these does not call the Zelinqa API or start a conversation. Copy the skills/zelinqa directory into your host's supported skills directory. No installation or credentials are granted by the skill itself.

Tests

uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pytest
uv build
uv run twine check dist/*

CI runs functional tests over the in-memory MCP transport with a fake SDK, plus lint, types and packaging. Live tests are separate and opt-in: ZELINQA_LIVE=1 with ZELINQA_LIVE_RUNTIME_KEY, then uv run pytest -m live tests/live. Optional revoked/read-only keys exercise authorization failures. Use a dedicated synthetic Zelinqa: the live tests create sessions and feedback. Unit tests alone do not prove the deployed API or database persistence.

Apache-2.0. See SECURITY.md for vulnerability reporting.