# StackKits MCP Connector

StackKits has one user-facing MCP connection named `stackkit`.

Implementation has two entrypoints for that same connector:

- local adapter: `stackkit-mcp` over stdio or loopback HTTP;
- durable endpoint: `stackkit-server` on the target host at `POST /mcp` and `GET /openmcp.json`.

`https://stackkit.cc/openmcp.json` is read-only website discovery for installers, docs, schemas, OpenAPI, prompts, and local connector configuration. It is not the execution connector.

`https://stackkit.cc/planner` is a separate page-side WebMCP surface. Its four v2alpha1 `stackkits_*` tools (`stackkits_list_catalog`, `stackkits_get_module_profiles`, `stackkits_assess_capacity`, and `stackkits_prepare_handoff`) read the public CUE-derived catalog, expose explicit use-case/module-profile facts, compare user-declared capacity, and prepare a non-executing CLI handoff. They neither become part of the durable `stackkit` connector nor execute on a target. The Planner remains usable when the browser does not implement WebMCP.

`stackkit-mcp` uses the same tool/resource/prompt registration as `stackkit-server`, so it is an adapter for the same StackKits MCP connector, not a second connector.

Use `/getting-started/installation-processes.md` to choose the right path by configuration/individualization degree, access options, and automation degree.

Website discovery and Planner WebMCP do not execute target actions. If an agent starts from the website and then installs or manages a server, it switches to the generated CLI handoff, shell, SSH, local MCP, or an explicitly protected target MCP endpoint. `stackkit compat` on the actual host remains mandatory.

Transport stance:

- Standard remote MCP uses Streamable HTTP on `POST /mcp`.
- `stackkit-mcp` stdio is the local subprocess adapter.
- WebSocket would be a custom transport/gateway, not the default interoperable StackKits surface.
- Durable external access to `stackkit-server /mcp` is a target day-2 capability after install, not the current default first-install path.

Default stance:

- read-only tools are available by default;
- write tools require `STACKKIT_MCP_ALLOW_WRITE=true`;
- MCP HTTP token auth uses `STACKKIT_MCP_TOKEN`;
- every tool declares truthful read-only, idempotent, destructive, and open-world hints; only tools that reach beyond the target host, such as release lookup and Federation send, are open-world.
- non-loopback access must be protected through tunnel, VPN, private network, mTLS/reverse proxy, or an OAuth-aware gateway.

Native read-only tools include docs search, API lookup, OpenAPI retrieval,
install plans, self-check plans, State Console metadata, validation, generate
preview, config read, status, verify, logs, and compatibility checks. The MCP
Doctor tool is exact-v0.6 compatibility only and is not advertised by native
v0.7+ discovery.

The installed `stackkit` CLI is controllable through the connector. Every
public CLI command is either an MCP tool projected from the shared StackKits
operation catalog or an explicit exception with a recorded reason: help,
completion and other terminal UX, agent bootstrap helpers, aliases,
exact-v0.6 compatibility verbs, repository tooling, and commands that would put
a secret value (such as `secrets reveal` or a one-time passkey URL) into the MCP
transcript. `stackkit operations --json` lists the projected operations.

Read-only operation tools (status, verify, logs, drift, host preflight, service
logs, users and more) register in `actions` mode. Mutating operation tools,
from `stackkit_init` and `stackkit_apply` to service control and restore
activation, execute local CLI-equivalent StackKits operations only and
additionally require `STACKKIT_MCP_ALLOW_WRITE=true`, the exact operation ID,
and explicit local Owner approval. `stackkit_config_set` is the create-only CUE
authoring tool.

The connector embeds the StackKits State Console at
`ui://stackkits/state-console.html`. It reviews a local workspace, an explicitly
chosen Kit configuration, the canonical plan, and Owner evidence. It is not a
Wizard or recommendation engine. It stages Apply for operation-specific agent
and Owner approval and never invokes `stackkit_apply` directly.

The connector exposes individual native actions and no combined rollout/update
macro. `stackkit_apply` consumes only the verified local artifact closure. This
surface does not run `stackkit app add`, customer app rollout,
managed-serverless provisioning, SaaS placement orchestration, or internal
Kombify operator MCPs.

Recommended single local connection:

```toml
[mcp_servers.stackkit]
command = "stackkit-mcp"
args = ["--mode", "docs,local,server,actions"]
```

Native local connector:

```text
POST http://localhost:8082/mcp
GET  http://localhost:8082/openmcp.json
```

Protected remote connector target:

```text
POST https://<protected-target>/mcp
GET  https://<protected-target>/openmcp.json
```