Skip to main content
The zelinqa-mcp server is available on PyPI. It runs locally in stdio, uses the Python SDK, and calls the public API. It does not contain the engine or access the database directly. You need Python 3.11+ and a runtime key for a published domain.

MCP quickstart

Configure your host, start a conversation, and inspect the available tools.

Install in your tool

Prepare a published domain, a runtime key and uv (uvx). Python 3.11+ is required.
With your key already available in the terminal’s ZELINQA_API_KEY environment variable:
Restart Claude Code, then use /mcp to check the connection. Official guide.
The key grants access to your domain. CLI commands save its value in the host’s local configuration. Keep these files private, never commit them, and never put the key in a conversation. Use a trusted host.
The server runs locally over stdio: there is no HTTP MCP URL to paste. uvx installs the package from PyPI and starts it; that process calls the Zelinqa API over HTTPS. If your host cannot find uvx, use its absolute path in the configuration.
To update an existing installation or choose between @latest and a fixed version, see MCP versions and updates.

Versions

Publishing a release does not update an already running MCP server. Behavior depends on the command saved in your host: In the host’s JSON configuration, keep "command": "uvx" and replace only "args": ["zelinqa-mcp"] with "args": ["zelinqa-mcp@latest"] or "args": ["zelinqa-mcp@1.0.1"]. Preserve environment variables and other options. Prefer a tested version in production. 1.0.1 is an example of a fixed version, not a promise that it is the latest release. To request the latest version and check what this command would launch, without a key or a Zelinqa API call:
To check a fixed version:
These commands may download a package; they do not change the host’s configuration or its running process. If you chose a persistent installation with uv tool install and launch zelinqa-mcp directly, use:
The latter method respects the installation constraint. To change an exact version, reinstall with uv tool install "zelinqa-mcp==1.0.1". See uv’s version rules.

Check after an update

  1. Read the server changes, then update the host’s command if necessary.
  2. Restart its MCP server or fully quit and reopen the host. A new version does not replace the running process in place.
  3. Check the seven business tools, then run a test conversation against a demo domain: question, answer, zelinqa_status, and stopping. This test uses your quotas.
Restarting clears local handles. To resume a session, persist its ID and name, then configure both ZELINQA_SESSION_ID and ZELINQA_CONVERSATION before restarting; see recovery. Do not rely on automatic recovery.
Updating your application’s Python SDK does not update MCP: its isolated environment installs the dependencies declared by its own version.

Default business tools

The host names a conversation; the server retains session, question, and decision IDs locally. The model does not need to invent them. For an open question, zelinqa_next_question needs the person’s words in user_text. For a choice question, send exact displayed labels in choice_labels; a semi-open question may also use free_text. refused or asked_no_answer can be sent without text. Never invent an answer. zelinqa_adjust is for verified information, not guesses. 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. If the person already answered a question that was then replaced, send that answer with zelinqa_add_context, not zelinqa_next_question. The returned view contains ranked question candidates, their text and choices, progress, and warnings. A reached turn limit does not mean the objective was achieved. Internal ranking mechanisms are not returned.

Transport, security, and recovery

  • Use one stdio process per trusted host/user; HTTP hosting is not enabled.
  • Keep ZELINQA_API_KEY in the host environment, never in a conversation or repository. It is bound to one domain and the runtime scope.
  • Conversation names and up to 128 handles are kept in that process, without silent eviction. zelinqa_forget releases a handle.
  • To resume after a restart, the host must persist the session ID outside the model and provide both ZELINQA_SESSION_ID and ZELINQA_CONVERSATION. The latter must exactly match the name passed to zelinqa_start or zelinqa_next_question (for example, demo-42). Otherwise that name may start a new session instead. A session created only in a desktop host is not resumed automatically.
  • Serialize mutations to the same conversation. After an interruption or conflict, call zelinqa_status before deciding whether to send an answer again.
The --advanced mode exposes six low-level API-like tools and technical IDs. Manage questions in Studio or with the SDK configuration client, not with the default MCP business tools. The server offers the zelinqa://guide resource, the zelinqa_integration_check prompt, and a portable skill. Reading them does not create a session or call the API. See the public repository for host examples and advanced-mode details.