Cloakapps for AI agents

Developer reference for agent integrations

Everything an autonomous agent (or its developer) needs to discover, authenticate against, and call cloakapps' MCP server. Information-dense, machine-friendly, and the canonical source — start here.

1. Discovery

If your agent is crawling cloakapps for the first time, start with one of these:

https://www.cloakapps.com/llms.txt

Plain-text manifest pointing to all agent-relevant resources. Lowest-friction entry point.

Recommended
https://www.cloakapps.com/.well-known/mcp.json

JSON manifest of MCP server(s) hosted by cloakapps — endpoint URL, transport, auth model, advertised tools.

GET https://kms.cloakapps.com/kms/mcp/info

Live discovery endpoint on the KMS server itself. Returns the canonical tool list, JSON-RPC examples, and Codex/Cursor configs. Requires a Bearer token.

2. Quick start

Three steps from zero to a successful tool call.

Step 1 — Provision an agent credential

Sign in to kms-console, go to Agent access, click New credential. Pick the scopes the agent needs (see scope table below). You'll get a credential ID and a one-time secret — copy the secret now, it isn't shown again.

Step 2 — Verify the MCP endpoint is reachable
curl -H "Authorization: Bearer $CLOAK_AGENT_TOKEN" \
     https://kms.cloakapps.com/kms/mcp/info

Returns the canonical tool list and JSON-RPC example payloads.

Step 3 — Add to your MCP-enabled IDE/agent
Cursor / Claude Desktop / Codex
{
  "mcpServers": {
    "cloakKms": {
      "url": "https://kms.cloakapps.com/kms/mcp",
      "headers": {
        "Authorization": "Bearer $CLOAK_AGENT_TOKEN"
      }
    }
  }
}
Direct JSON-RPC (any client)
POST /kms/mcp
Content-Type: application/json
Authorization: Bearer $CLOAK_AGENT_TOKEN

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

3. Tool catalog

Nine HSM-backed primitives. The live JSON schema for each is at GET /kms/mcp/info; the table below summarises name, required scope, and intent. See the agents page for input/output examples.

Tool Scope Description
kms_list_masterkeysKEYS_READList masterkeys visible to the credential.
kms_read_public_keyPUBLIC_KEY_READReturn the PEM public key for a named masterkey.
kms_create_masterkeyKEY_GENERATEProvision a new HSM key (RSA / ECC / AES; SIGN / ENCRYPT / DERIVE usage).
kms_delete_masterkeyKEY_DELETEIrreversibly delete a masterkey from every keystore that holds it.
kms_signCRYPTO_SIGNSign a SHA-256 digest inside the HSM (RSA-PSS / RSA-PKCS / ECDSA).
kms_verifyCRYPTO_VERIFYVerify a signature against a masterkey's public half.
kms_encryptCRYPTO_ENCRYPTEncrypt bytes with an HSM-held key (RSA-OAEP / AES-CBC).
kms_decryptCRYPTO_DECRYPTDecrypt ciphertext with an HSM-held key.
kms_ecdh_deriveCRYPTO_DERIVEDerive an ECDH shared secret using an HSM-held ECC key and a peer public point.

4. Authentication & scopes

All requests carry Authorization: Bearer <token>. Two token kinds are accepted:

User JWT

Issued by the cloakapps Keycloak realm via the interactive console flow. Carries full user permissions; used by humans and by trusted host applications calling on the user's behalf.

Agent credential

Long-lived, scope-bound token issued via Agent access in kms-console. Per-credential scope is enforced before every operation — a credential without CRYPTO_DECRYPT scope cannot call kms_decrypt, even with a valid token. Credentials can be rotated, auto-rotated, or revoked instantly.

Scope names: KEYS_READ, PUBLIC_KEY_READ, CRYPTO_SIGN, CRYPTO_VERIFY, CRYPTO_ENCRYPT, CRYPTO_DECRYPT, CRYPTO_DERIVE, KEY_GENERATE, KEY_DELETE.

5. REST mirror

Every MCP tool also has a REST equivalent under /kms/users/{v}/agent-tools/. Use this if your agent framework doesn't speak MCP. Auth and scope enforcement are identical.

GET    /kms/users/1/agent-tools/keys
POST   /kms/users/1/agent-tools/read-public-key
POST   /kms/users/1/agent-tools/create-masterkey
POST   /kms/users/1/agent-tools/delete-masterkey
POST   /kms/users/1/agent-tools/sign
POST   /kms/users/1/agent-tools/verify
POST   /kms/users/1/agent-tools/encrypt
POST   /kms/users/1/agent-tools/decrypt
POST   /kms/users/1/agent-tools/ecdh-derive

6. Code samples

All examples assume CLOAK_AGENT_TOKEN and CLOAK_BASE environment variables.

Sign a digest (curl, REST)
curl -X POST "$CLOAK_BASE/kms/users/1/agent-tools/sign" \
  -H "Authorization: Bearer $CLOAK_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "agent-signing-key",
    "keyId": "0101",
    "algorithm": "ECDSA_SHA_256",
    "digestHex": "a4caf7bd…21083d95"
  }'
Call a tool over MCP (Python)
# pip install mcp
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async with streamablehttp_client(
    "$CLOAK_BASE/kms/mcp",
    headers={"Authorization": f"Bearer {token}"}
) as (read, write, _):
    async with ClientSession(read, write) as s:
        await s.initialize()
        result = await s.call_tool("kms_sign", {
            "alias": "agent-signing-key",
            "keyId": "0101",
            "algorithm": "ECDSA_SHA_256",
            "digestHex": digest_hex
        })
Call a tool from Claude Code / Cursor

Once the MCP config block from Step 3 is in place, ask the agent: "Use the cloakKms.kms_list_masterkeys tool to show me my available signing keys." The IDE will surface the tool list and call it on your behalf.

7. Errors

Errors return a typed body with a stable code, a human message, and a remediation hint. Examples:

{
  "code":        "KEY_NOT_FOUND",
  "message":     "The requested key was not found.",
  "retryable":   false,
  "remediation": "List available keys first and retry with a valid alias and keyId."
}

Stable codes: INVALID_REQUEST, KEY_NOT_FOUND, UNSUPPORTED_KEY_USAGE, UNSUPPORTED_ALGORITHM, DOWNSTREAM_FAILURE. Scope failures return HTTP 403.

8. Roadmap

Workflow tools planned but not yet shipped: