@qodalis/mcp-cli

A resilient Model Context Protocol server that gives Claude Code a Qodalis CLI server: its CLI commands, files, data explorer, jobs and plugin tools.

Every Qodalis CLI server (.NET, Node or Python) can expose an MCP endpoint at <server>/api/qcli/mcp. mcp-cli runs on your machine as a stdio MCP server and proxies to that endpoint: Claude Code sees exactly the server's tools, with the permissions of the account you configure. It handles sign-in, reconnects after network drops and lets you narrow what the assistant may use.

Highlights

• No tool-specific code. Tools come from the server's tools/list and are passed through unchanged (names, schemas, annotations); calls are forwarded. New commands on the server show up without updating the proxy.

• Token or password. Use an API token (QCLI_TOKEN), or sign in with QCLI_USER / QCLI_PASSWORD; an expired session is renewed automatically on the next call.

• Read-only mode (QCLI_READ_ONLY=true) exposes only the tools the server marks read-only, and refuses calls to anything else.

• Client-side allow and deny lists (QCLI_TOOLS, QCLI_EXCLUDE, trailing * allowed) on top of the server's own permissions.

• Self-healing connection. It connects on first use, never caches a failed connect, retries once when the connection drops, and fails fast (8 s) when the server is unreachable, with a message that says what to check.

• Clear errors: a rejected token, MCP not enabled on the server, a missing permission or an unreachable host each come back as one actionable sentence.

Related MCP server: Claude Code Manager WAN

Quick start

npx -y @qodalis/mcp-cli --help

The server must have MCP enabled (mcp option; see MCP endpoint). Default ports: .NET 8046, Node 8047, Python 8048.

Claude Code

claude mcp add qcli -- npx -y @qodalis/mcp-cli

then set the environment in ~/.claude.json:

{
  "mcpServers": {
    "qcli": {
      "command": "npx",
      "args": ["-y", "@qodalis/mcp-cli"],
      "env": {
        "QCLI_URL": "http://localhost:8047",
        "QCLI_TOKEN": "qcli_pat_..."
      }
    }
  }
}

or sign in with a user name and password instead of a token:

"env": {
  "QCLI_URL": "http://localhost:8047",
  "QCLI_USER": "ops",
  "QCLI_PASSWORD": "********"
}

The same in one command, with -e flags:

claude mcp add qcli -e QCLI_URL=http://localhost:8047 -e QCLI_TOKEN=qcli_pat_... -- npx -y @qodalis/mcp-cli

Add --scope user to make it available in every project. With --scope project the entry goes into the project's .mcp.json, which is usually committed: keep the secret out of it with "QCLI_TOKEN": "${QCLI_TOKEN}" and set the variable in your shell. A .env file works too:

{ "command": "npx", "args": ["-y", "@qodalis/mcp-cli", "--env-file", "/path/to/.env"] }

Pin a version in shared configs (@qodalis/mcp-cli@0.1.0) so an upgrade is a deliberate change.

Getting a token

In the web CLI connected to the server (users plugin), signed in as the account the assistant should act as:

token create claude --expires=90
# token create claude --permissions=commands:execute,files:read   (narrower scope)

The token (qcli_pat_…) is shown once. Without the web CLI, sign in and create one with curl:

SESSION=$(curl -s http://localhost:8047/api/v1/qcli/sessions \
  -H 'Content-Type: application/json' -d '{"username":"ops","password":"..."}' | jq -r .token)
curl -s http://localhost:8047/api/v1/qcli/tokens -H "Authorization: Bearer $SESSION" \
  -H 'Content-Type: application/json' -d '{"name":"claude","expiresInDays":90}' | jq -r .token
curl -s -X DELETE http://localhost:8047/api/v1/qcli/sessions/current -H "Authorization: Bearer $SESSION"

A server without the users plugin protects its endpoint with a static token (its mcp.token option): put that value in QCLI_TOKEN. If it sets none, the endpoint is open and no auth variable is needed.

Configuration

Every setting is an environment variable. QODALIS_CLI_* names are accepted as aliases for every key.

Set either QCLI_TOKEN or QCLI_USER + QCLI_PASSWORD, not both.

Tools

The tools are whatever the server exposes to your account. A typical server offers:

Each one is limited by the account's permissions on the server (for example commands:execute, files:read / files:write, data:query, jobs:manage), and by the token's scope when it was created with --permissions.

Read-only mode

With QCLI_READ_ONLY=true the proxy lists only the tools the server annotates readOnlyHint: true (such as server_info, fs_list, fs_read, data_schema, jobs_list) and refuses calls to any other tool before they reach the server. Command tools carry no read-only annotation, so they are hidden in this mode; add the ones you want with a separate, non-read-only entry and QCLI_TOOLS.

The filter is defence in depth. The real boundary is the account: give the assistant a user (or a token scope) with only the permissions it should have.

Several servers

Add one entry per server (and per access level) with a distinct name:

{
  "mcpServers": {
    "qcli-dev": {
      "command": "npx",
      "args": ["-y", "@qodalis/mcp-cli"],
      "env": { "QCLI_URL": "http://localhost:8047", "QCLI_TOKEN": "qcli_pat_dev..." }
    },
    "qcli-prod": {
      "command": "npx",
      "args": ["-y", "@qodalis/mcp-cli"],
      "env": {
        "QCLI_URL": "https://cli.example.com",
        "QCLI_TOKEN": "qcli_pat_prod...",
        "QCLI_READ_ONLY": "true"
      }
    },
    "qcli-prod-jobs": {
      "command": "npx",
      "args": ["-y", "@qodalis/mcp-cli"],
      "env": {
        "QCLI_URL": "https://cli.example.com",
        "QCLI_TOKEN": "qcli_pat_prod...",
        "QCLI_TOOLS": "jobs_*,server_info",
        "QCLI_EXCLUDE": "jobs_cancel"
      }
    }
  }
}

Troubleshooting

claude mcp list shows whether each server connects; inside a session /mcp shows its status and tools and lets you reconnect. The proxy logs to stderr (claude --debug shows it).

How reconnection works

1. The proxy connects to the endpoint on the first tools/list or tools/call, not at startup, so Claude Code starts even when the server is down.

2. A failed connect is not cached: the next call tries again.

3. A connection-level error (refused, reset, socket closed, DNS failure) drops the connection and retries the request once on a fresh one. A connect timeout is not retried, so an unreachable host fails within QCLI_CONNECTION_TIMEOUT.

4. With QCLI_USER / QCLI_PASSWORD, a 401 signs in again and retries once.

5. The tool list is cached for 60 s; a call to a tool the proxy does not know yet refreshes it first, so new server commands work without a restart.

Security notes

• Tokens and passwords are read from the environment, sent only to QCLI_URL, and never written to logs or tool results.

• Prefer an API token with a narrow --permissions scope and an expiry over a password; revoke it with token revoke <id> when it is no longer needed.

• Use https:// for anything but localhost. QCLI_TRUST_CERT=true disables certificate verification for this process; use it only for self-signed certificates you control.

• Nothing is written to stdout except the MCP protocol stream.

See SECURITY.md for reporting vulnerabilities.

Library use

The pieces are exported for embedding:

import { createProxyServer, loadConfig, RemoteServer } from '@qodalis/mcp-cli';

const config = loadConfig(process.env);
const remote = new RemoteServer(config, { clientInfo: { name: 'my-app', version: '1.0.0' } });
const server = createProxyServer(remote, config); // a low-level MCP Server: connect any transport

Development

npm install
npm run build
npm test             # unit tests and stdio end-to-end tests against a fake server (build first)
npm run typecheck
npm run check-format
npm run dev -- --env-file .env   # run from source

See CONTRIBUTING.md.

License

MIT © Qodalis Solutions SRL