kc-mcp-server — Kvindo Cloud MCP Server

npm version License: MIT Node.js

An MCP (Model Context Protocol) server for Kvindo Cloud — lets any MCP-compatible AI client (Claude Desktop, Claude Code, and other LLM agents/AI tools) list, inspect, create, update, and delete your Kvindo Cloud resources (VMs, Volumes, S3 buckets, Kubernetes, Load Balancers, VPNs, PostgreSQL, and more) conversationally.

It's a thin wrapper over Kvindo Cloud's own REST API — the same API the kc CLI, Terraform provider, and Python SDK already use.

Read-only by default. Creating, updating, or deleting resources requires explicitly opting in via environment variables — see Write access below.

1. Install & configure

Requires an MCP client (e.g. Claude Desktop or Claude Code) and a Kvindo Cloud Personal Access Token: console → IAM → Tokens → Create token.

Add to your MCP client's config (for Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "kvindo-cloud": {
      "command": "npx",
      "args": ["-y", "kc-mcp-server"],
      "env": {
        "KVINDO_API_TOKEN": "<your token>"
      }
    }
  }
}

Restart your client. The server validates the token at startup (one cheap authenticated call) and fails fast with a clear message if it's invalid or expired.

Multiple accounts / environments

Run multiple named server instances, each with its own env block:

{
  "mcpServers": {
    "kvindo-cloud-prod": {
      "command": "npx",
      "args": ["-y", "kc-mcp-server"],
      "env": { "KVINDO_API_TOKEN": "<prod token>" }
    },
    "kvindo-cloud-dev": {
      "command": "npx",
      "args": ["-y", "kc-mcp-server"],
      "env": {
        "KVINDO_API_TOKEN": "<dev token>",
        "KVINDO_API_URL": "https://dev-cloud-api.avant-it.ru"
      }
    }
  }
}

There's no built-in multi-profile switching within a single server instance — one process is one account.

2. Environment variables

Variable	Required	Default	Notes
`KVINDO_API_TOKEN`	yes	—	Personal Access Token from console → IAM → Tokens.
`KVINDO_API_URL`	no	`https://cloud-api.kvindo.ru`	Point at a different environment (e.g. dev).
`KVINDO_MCP_ALLOW_WRITE`	no	`false`	Must be exactly `"true"` or `"false"`. Enables `create_or_update_resource`.
`KVINDO_MCP_ALLOW_DELETE`	no	`false`	Must be exactly `"true"` or `"false"`. Enables `delete_resource`. Independent of `ALLOW_WRITE` — you can allow create/update without exposing delete.

Any other value for the two ALLOW_* flags (e.g. "1", "yes") fails startup rather than silently falling back to read-only or write-enabled — a typo shouldn't silently change your safety posture in either direction.

3. Write access

Set these per-invocation in your MCP client config, not left permanently on in a shared profile:

"env": {
  "KVINDO_API_TOKEN": "...",
  "KVINDO_MCP_ALLOW_WRITE": "true",
  "KVINDO_MCP_ALLOW_DELETE": "true"
}

When a gate is off, its tool is absent from the tool list entirely — the model can't discover or attempt it, not just get an error when it tries. delete_resource additionally requires a confirm: true argument on every call, on top of the env-var gate.

Known limitation: these gates are process-wide, not per-call or per-conversation. Enabling delete for one task leaves it enabled until you restart the server with different env vars. Every write/delete call is logged to stderr with a timestamp as a local audit trail.

All writes (create, update, delete) are asynchronous — the response carries a requestId; poll get_request_status until succeeded: true rather than assuming the change applied immediately.

4. Available tools

Tool	Gate	Description
`list_resource_types`	always	List every resource type this server can manage.
`describe_resource_type`	always	Get the JSON Schema for a type's manifest (`spec`/`status`).
`list_resources`	always	List resources of a type, filtered by label, auto-paginated (capped at 5 pages / 100 per page — narrow your filter if truncated).
`get_resource`	always	Fetch one resource by id.
`get_request_status`	always	Poll an async change request.
`create_or_update_resource`	`KVINDO_MCP_ALLOW_WRITE`	Create or update (idempotent on `manifest.metadata.id`). Validated against the type's schema client-side before sending.
`delete_resource`	`KVINDO_MCP_ALLOW_DELETE` + `confirm: true`	Delete by id. Usually irreversible.

There's no folderId filter at the API level — filter by label if your resources carry a folder-identifying label.

5. Example

"List my running VMs, then create a new SSH key called laptop with this public key: ..."

The model calls list_resources({ type: "vm" }), then — if writes are enabled — describe_resource_type({ type: "ssh-key" }) to see the manifest shape, then create_or_update_resource({ type: "ssh-key", manifest: {...} }), then polls get_request_status until it succeeds.

6. Troubleshooting

Symptom	Cause / fix
Server fails to start: `KVINDO_API_TOKEN is required`	Set the env var — see Install & configure.
Server fails to start: `token check failed (Unauthorized...)`	Token is invalid or expired — generate a new one in console → IAM → Tokens.
A write/delete tool doesn't show up	Its `KVINDO_MCP_ALLOW_*` gate isn't set to exactly `"true"` — see Write access.
`create_or_update_resource` fails with "failed schema validation"	The manifest doesn't match the type's schema — call `describe_resource_type` first. This is a client-side convenience check; the API remains the authority.
`list_resources` result says `truncated: true`	Hit the 5-page auto-pagination cap. Narrow the `labels` filter, or pass the returned `enumeratorId` to continue.
A resource type is missing from `list_resource_types`	The backend added it after this server's release — see Resource-type drift.

7. Resource-type drift

The list of resource types and their schemas is generated from Kvindo Cloud's OpenAPI spec at release time, not fetched live — a genuinely new backend resource type won't appear until the next release of this package (same as kc/the Python SDK until their next release). A daily CI check compares against the live spec and files a tracking issue on drift; see CHANGELOG.md for what's shipped.

Development

npm install
npm run generate     # regenerate src/resource-types.generated.ts from the dev API's swagger.json
npm run typecheck
npm run lint
npm test
npm run build

Part of the Kvindo Cloud developer toolchain:

kc CLI — kubectl-style command-line client for Kvindo Cloud.
kc-sdk-python — Python SDK for the Kvindo Cloud API (PyPI).
terraform-provider-kvindo — Terraform provider (Registry).
Kvindo Cloud console — web UI and API.

License

MIT