Pular para o conteúdo
Wippy

Keeper over MCP

Este conteúdo não está disponível em sua língua ainda.

Keeper over MCP

Section titled “Keeper over MCP”

Wippy Keeper is the control plane for a running Wippy app — a registry workbench, filesystem↔registry governance, agent/task orchestration, Hub install, knowledge base, logs and process inspection, and a Git review/push flow, all behind a built-in UI. Its defining feature is that it exposes those operator capabilities to AI clients (Claude, Codex, …) over MCP (Model Context Protocol). This page adds Keeper to an app and connects an MCP client to it.

What You’ll Build

Section titled “What You’ll Build”
  1. Keeper added to an app scaffolded from app-template.
  2. The Keeper UI at /app/keeper and the MCP endpoint at /keeper-mcp/.
  3. A scoped MCP token, and an MCP client configured to drive the app through Keeper.

Prerequisites

Section titled “Prerequisites”

  • An app from app-template. It already provides everything Keeper binds to: app:gateway, app:api, app:db, app:processes, app.security:admin, and app.env:store.

  • The Keeper module installed:

    Terminal window
    wippy add keeper/keeper
    wippy install

Add Keeper

Section titled “Add Keeper”

Declare the dependency and bind it to the app’s resources. Only admin_scope is required (no default); the rest default to the names app-template already uses, shown here explicitly for clarity:

src/app/deps/_index.yaml
- name: keeper
  kind: ns.dependency
  component: keeper/keeper
  parameters:
    - { name: app_db,         value: app:db }
    - { name: admin_scope,    value: app.security:admin }
    - { name: env_storage,    value: app.env:store }
    - { name: public_gateway, value: app:gateway }   # hosts /keeper-mcp/
    - { name: mcp_route,      value: /keeper-mcp/ }
    - { name: ui_server,      value: app:gateway }
    - { name: process_host,   value: app:processes }

Start the app:

Terminal window
wippy run

Keeper auto-mounts three surfaces:

  • UI — /app/keeper
  • MCP transport — /keeper-mcp/ on the public gateway
  • Token API — on app:api (/keeper/mcp/tokens, /keeper/mcp/scopes)

The MCP transport is gated by the MCP_ENABLED environment variable (default true); set it to false to close the endpoint.

Mint an MCP Token

Section titled “Mint an MCP Token”

Tokens are issued by an admin user, scoped, and shown exactly once. Create one via the token API (or the MCP page in the Keeper UI):

Terminal window
curl -X POST http://localhost:8085/api/v1/keeper/mcp/tokens \
  -H 'Authorization: Bearer <admin-session-token>' \
  -H 'Content-Type: application/json' \
  -d '{"label": "claude-dev", "preset": "developer"}'
# -> { "success": true, "token": { "token": "wkmcp_<64 hex>", ... } }

preset bundles a set of scopes. Available presets: root, developer, wippy_operator, observer, knowledge_manager, explorer_tools_only. For finer control, pass an explicit scopes array instead (e.g. registry.read, state.write, git.pr, tasks.run, knowledge.read). The raw wkmcp_... token is returned once and stored only as a hash — copy it immediately.

Connect a Client

Section titled “Connect a Client”

Point an MCP client at the endpoint with the token as a bearer header. For Claude Code / Codex, an .mcp.json in the project root:

{
  "mcpServers": {
    "keeper": {
      "type": "http",
      "url": "http://localhost:8085/keeper-mcp/",
      "headers": { "Authorization": "Bearer wkmcp_<token>" }
    }
  }
}

Use the app’s public base URL in place of http://localhost:8085 in a deployed environment.

How the MCP Surface Works

Section titled “How the MCP Surface Works”

Keeper does not expose a flat, fixed tool list. It presents a few meta-tools plus traits that activate concrete tools on demand, so the surface stays small until you opt into a capability:

  • session_info — always available; reports the session’s scopes and active traits.
  • list_traits / describe_trait — discover what’s available.
  • use_trait / drop_trait (and set_traits) — activate or remove a trait; this emits an MCP notifications/tools/list_changed, so the visible tools change live.
  • list_tools / call_tool — enumerate and invoke the tools a trait materialized.

What a token can activate is bounded by its scopes — roughly registry.*, state.*, hub.*, knowledge.*, git.*, components.*, tasks.*, agents.*, tests.run, logger.*, env.*, functions.call, app.ui (plus mcp.root for full admin bypass). The token’s access_mode (any / traits / tools_only) further constrains how it may call tools.

Notes

Section titled “Notes”
  • Governance scope — set GOV_MANAGED_NAMESPACES=app so Keeper’s filesystem↔registry sync only governs your app’s namespace. Do not add keeper, wippy, or userspace unless you are developing those modules.
  • Security — tokens are bound to the issuing admin identity and a scope set, stored as SHA-256, and revocable via POST /keeper/mcp/tokens/revoke. The /keeper-mcp/ route runs no auth middleware; the handler enforces the bearer token itself.
  • Reference app — app-keeper is the worked example that wires Keeper into an app shell; copy its src/app/deps/_index.yaml block if you want a known-good setup.

Next Steps

Section titled “Next Steps”