> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect the MCP server

> Install Zelinqa MCP and run a conversation from a compatible host.

You need Python 3.11+, `uvx`, and a `runtime` key created in Zelinqa Studio for a published domain. The public package is [`zelinqa-mcp` on PyPI](https://pypi.org/project/zelinqa-mcp/).

## Install in your tool

Prepare a [published domain](/en/quickstart/configure-domain), a [`runtime`](/en/quickstart/generate-api-key) key and [uv](https://docs.astral.sh/uv/getting-started/installation/) (`uvx`). Python 3.11+ is required.

<Tabs>
  <Tab title="Claude Code">
    With your key already available in the terminal's `ZELINQA_API_KEY` environment variable:

    ```bash theme={null}
    claude mcp add --scope user \
      --env ZELINQA_API_KEY="$ZELINQA_API_KEY" \
      --transport stdio zelinqa -- uvx zelinqa-mcp
    claude mcp list
    ```

    Restart Claude Code, then use `/mcp` to check the connection. [Official guide](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab title="Codex">
    With your key already available in the terminal's `ZELINQA_API_KEY` environment variable:

    ```bash theme={null}
    codex mcp add zelinqa \
      --env ZELINQA_API_KEY="$ZELINQA_API_KEY" \
      -- uvx zelinqa-mcp
    codex mcp list
    ```

    Reopen your Codex session after adding the server. [Official guide](https://developers.openai.com/codex/mcp).
  </Tab>

  <Tab title="Cursor">
    Add this entry to your **personal** MCP configuration, `~/.cursor/mcp.json`, preserving existing servers.

    ```json theme={null}
    {
      "mcpServers": {
        "zelinqa": {
          "command": "uvx",
          "args": ["zelinqa-mcp"],
          "env": {
            "ZELINQA_API_KEY": "YOUR_RUNTIME_KEY"
          }
        }
      }
    }
    ```

    Replace the placeholder and check that the server is enabled in Cursor's MCP settings.
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings → Developer → Edit Config** and add this server to `mcpServers`, preserving existing entries:

    ```json theme={null}
    {
      "mcpServers": {
        "zelinqa": {
          "command": "uvx",
          "args": ["zelinqa-mcp"],
          "env": {
            "ZELINQA_API_KEY": "YOUR_RUNTIME_KEY"
          }
        }
      }
    }
    ```

    Replace the placeholder, save, and fully restart Claude Desktop.
  </Tab>
</Tabs>

<Warning>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.</Warning>

<Note>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.</Note>

To update an existing installation or choose between `@latest` and a fixed version, see [MCP versions and updates](/en/integrations/mcp#versions).

## Verify with a first conversation

Ask your host:

> Use Zelinqa to start a conversation named demo-42. Ask the returned question, wait for my answer, and continue one question at a time. Do not invent answers.

The host should call `zelinqa_start`, display a question from your domain, and use `zelinqa_next_question` after your reply. Check that the seven [business tools](/en/integrations/mcp) are available. Installation alone does not create a conversation; business calls use your API and its quotas.

## First turn

Call these tools in order from your host:

```json theme={null}
{"tool":"zelinqa_start","arguments":{"conversation":"demo-42"}}
```

Actually display the returned question and wait for the person. Calling `zelinqa_next_question` with no answer merely redisplays the pending question. After receiving an answer to an open question:

```json theme={null}
{"tool":"zelinqa_next_question","arguments":{"conversation":"demo-42","user_text":"I'm looking for a sofa for my living room."}}
```

For a choice question, pass `choice_labels` with the exact displayed label, for example `{"choice_labels":["Contemporary"]}`. For a semi-open question, add `free_text` only when the person provided an explanation. For a genuine refusal or no answer, use `outcome: "refused"` or `outcome: "asked_no_answer"` without inventing text. The tool response contains the next question, progress, and warnings.

Use `zelinqa_adjust` to add data already confirmed without asking a question or consuming a turn. Use `zelinqa_feedback` for an observed business result, not a prediction. After an interruption, call `zelinqa_status` before sending an answer again. `zelinqa_forget` releases the local handle but does not erase the API session.

<Warning>Conversation names alone do not survive an MCP process restart. To resume `demo-42`, persist the session ID in your host/backend and provide **`ZELINQA_SESSION_ID` and `ZELINQA_CONVERSATION=demo-42`** to the new process. The name must exactly match the one passed to the tool; otherwise a new session may be created. Do not place the ID in the model prompt.</Warning>

See the [full MCP overview](/en/integrations/mcp) and [source guide](https://github.com/Zelinqa/zelinqa-mcp/blob/main/README.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.