Kc 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

---

Related projects

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