Zelinqa MCP server

Zelinqa MCP

<!-- mcp-name: io.github.Zelinqa/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 ZELINQAAPIKEY 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 zelinqanextquestion. 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 choicelabels: ["Contemporary"]. Use candidaterank 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 usertext. An outcome alone is accepted only for refused or askednoanswer, for any question type. Closed and semi-open questions accept exact choicelabels; semi-open choices can also include freetext. assistanttext 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.

Shortened. The full README is on GitHub.