{ "tenantUrl": "https://…cumulocity.com", "tenantId": "t123", "tenantNamespaces": ["c8y", "dtm", "knowledge_base_ms"], // null = the check could not run, see `warnings` "warnings": [], "servers": [ { "name": "MaStR registry", "namespace": "MaStR_registry", // derived — store THIS and send it in the header from now on "status": "ok", // ok | invalid | namespace-taken | unreachable "server": { "name": "mastr-mcp", "version": "1.0.0" }, "tools": [{ "name": "search_units", "description": "…" }] } ] } ``` - **`name` may be free-form here.** It is sanitized into the namespace exactly as a contextPath is (`MaStR registry` → `MaStR_registry`, the same rule that makes `knowledge-base-ms` into `knowledge_base_ms`). An identifier passes through unchanged. - **`status` is the field to branch on**, and `namespace-taken` is the interesting one: reserved name, a namespace this tenant already holds, or a duplicate inside the same request. That is the collision that would otherwise be a silent skip at run time — `namespaceTakenBy` says who holds it. Tools are still reported for a taken entry, so renaming is the only fix needed. - **The header contract does not change.** Derivation is a configure-time convenience: resolve once, store the `namespace` you got back, keep sending it verbatim. The agent-visible namespace stays stable even if the derivation is refined later. - **Validation is the header's own**, so this route cannot green-light an entry the header would then 400. - **Nothing is persisted, and nothing is cached.** mc8yp holds no external server configuration of its own, and the handshake bypasses the per-session tool-list cache so the answer always reflects the credentials as sent. - Requires user auth (Authorization header or session cookie), like `POST /refresh-apis`. ## Two ways to run it - **Microservice mode** (recommended for production) — deploy inside Cumulocity IoT, expose `/mcp`, integrate with [AI Agent Manager](https://cumulocity.com/docs/ai/aim-introduction/). Auth comes from the request and the service user. - **CLI mode** (local development) — run locally over stdio with an MCP client such as Claude Desktop. Credentials are stored in the OS keyring. --- ## Quick start — Microservice (recommended) 1. Download the latest release zip from [GitHub Releases](https://github.com/schplitt/mc8yp/releases). 2. Upload the `.zip` in Cumulocity **Application Management**. 3. Subscribe the application in your tenant. 4. Point your agent at: ```txt https://.cumulocity.com/service/mc8yp-server/mcp ``` No extra credential setup is required — the microservice uses Cumulocity's deployment environment and request authentication. The microservice manifest declares `exposeMcpServers`, so once the application is subscribed it auto-registers with AI Agent Manager as an MCP server at `/service/mc8yp-server/mcp` (with the user's authentication forwarded). No manual MCP server entry is needed in AI Agent Manager. **Example: read-only production agent** (allow only safe GETs): ```txt /mcp?allow=GET:/inventory/**&allow=GET:/alarm/**&allow=GET:/measurement/** ``` Or via headers: ```http POST /mcp HTTP/1.1 mc8yp-allow: GET:/inventory/** mc8yp-allow: GET:/alarm/** mc8yp-allow: GET:/measurement/** ``` See [Access policy](#access-policy) for the full rule syntax. --- ## Quick start — Local CLI ### Platform support | Platform | Supported | Notes | | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | macOS | ✅ native | Keychain is used for credentials | | Linux | ✅ native | Secret Service (libsecret) is used for credentials | | Windows | ❌ | Use [WSL 2](https://learn.microsoft.com/windows/wsl/) (see [WSL 2 one-time setup](#wsl-2-one-time-setup) below) or the microservice mode instead | The sandboxed V8 runtime ([`@iso4/sandbox`](https://www.npmjs.com/package/@iso4/sandbox)) communicates with a Rust subprocess over Unix domain sockets, which is why native Windows is not supported. ### Install and run ```sh # Run directly (recommended) pnpm dlx mc8yp # Pick a specific bundled core OpenAPI build for the codemode tool pnpm dlx mc8yp --spec 2025 # Or install globally npm install -g mc8yp mc8yp ``` ### Add credentials `mc8yp creds add` prompts for tenant URL, username, and a masked password, and writes them to the OS keyring. ```sh pnpm dlx mc8yp creds add # add credentials (interactive, masked password) pnpm dlx mc8yp creds list # list stored credentials pnpm dlx mc8yp creds remove # remove stored credentials ``` On macOS and standard desktop Linux this works out of the box. On **WSL 2** the keyring stack is not wired up by default and needs a one-time bootstrap:

WSL 2 one-time setup — required before mc8yp creds add works on WSL

A fresh WSL 2 distro has no Secret Service provider, no session D-Bus, and no `login` keyring collection, so `@napi-rs/keyring` (used by `mc8yp creds add`) has nothing to talk to. On a normal desktop Linux all of this is wired up automatically by the display manager and PAM; on WSL you have to do it once manually. **1. Inside WSL, install the keyring stack:** ```sh sudo apt install -y libsecret-tools dbus-x11 sudo apt install -y libpam-gnome-keyring ``` - `libsecret-tools` provides `secret-tool` and pulls in `libsecret` (the client library `@napi-rs/keyring` uses). - `dbus-x11` provides `dbus-launch` so a session D-Bus can be started in a headless shell. - `libpam-gnome-keyring` installs `gnome-keyring-daemon` (the actual Secret Service provider) and its PAM module. **2. Force the keyring database to initialize:** ```sh secret-tool store --label="init" init init ``` A throwaway write so `gnome-keyring-daemon` creates its on-disk store. **3. Wire up PAM so the keyring auto-unlocks at login:** ```sh sudo bash -c 'cat >> /etc/pam.d/login <" gdbus call --session \ --dest org.freedesktop.secrets \ --object-path /org/freedesktop/secrets \ --method org.freedesktop.Secret.Service.CreateCollection \ "{'org.freedesktop.Secret.Collection.Label': <'login'>}" \ "" ``` **7. Trigger the keyring passphrase prompt once:** ```sh secret-tool store --label="test" service myservice username myuser ``` This opens a prompt to set the keyring passphrase. You can leave it **empty** — the keyring will then auto-unlock without prompting later, which is what you want for headless WSL. After this, `mc8yp creds add` will work.

### Activate a tenant Adding credentials does **not** auto-activate a tenant. Live API calls only run against a tenant once one has been selected, and the agent does that itself through MCP tools: 1. The agent calls `status` to see stored credentials, the current active tenant, and the API namespaces currently visible. 2. The agent calls `set-active-tenant` with one of the tenant URLs. The selection is written to `~/.config/mc8yp/active-tenant.json` and reused across CLI restarts. 3. The agent runs `codemode` as needed. Each result starts with a marker line showing which tenant it ran against. To switch tenants, call `set-active-tenant` again. To stop targeting any tenant (browse bundled specs only), call it with `tenantUrl: null` — discovery (`codemode.search`/`describe`, `docs`) keeps working against the bundled reference snapshots, while live API calls return a missing-auth error so the agent cannot accidentally hit a tenant. If the active tenant's credentials are removed via `mc8yp creds remove`, the next `status` call clears the active tenant automatically. ### Connect a local MCP client For Claude Desktop or any stdio MCP client: ```json { "servers": { "mc8yp": { "type": "stdio", "command": "pnpm", "args": ["dlx", "mc8yp"] } } }

mc8yp

Installation