konecty Konecty Meta
Procedural guide for all Konecty metadata administration. Execution happens
through Konecty's admin MCP tools (meta_*) — this skill teaches which tool to call,
with which payload shape, and which guardrails to respect. It ships no scripts and
makes no HTTP calls.
Requires the
konecty-adminMCP server connected (Konecty admin MCP at<company-url>/admin-mcp) and a user withadmin: true. If themeta_*tools are not available, stop and guide the user through the konecty-setup skill.
Authentication (two paths)
- Interim (today): the
konecty-adminserver entry is registered with anAuthorization: Bearer <authTokenId>header, whereauthTokenIdcomes from an admin user's OTP login (obtained during setup). When it expires, re-run the setup "fix auth" flow to get a new token and re-register the header. - Target (OAuth): Konecty grants the
adminOAuth scope to trusted clients (provisioned viaOAUTH_CLIENTS_JSON, ADR-0011) at consent — only for users withadmin: true, shown unchecked with a risk warning. Once your Konecty ships it, switching is a re-registration only (claude mcp remove+addwith--client-id/--callback-port; see konecty-setup) — nothing in this skill changes.
Either way, tools are called without any token argument — auth travels in the HTTP header. See references/auth.md.
Tool inventory (admin MCP — 12 tools)
| Tool | Input | Purpose |
|---|---|---|
meta_read |
name |
Read a document metadata object by name |
meta_document_upsert |
id, document |
Create/update a document schema |
meta_list_upsert |
id, list |
Create/update a list meta |
meta_view_upsert |
id, view |
Create/update a view (form) meta |
meta_access_upsert |
id, access |
Create/update an access profile |
meta_pivot_upsert |
id, pivot |
Create/update a pivot meta |
meta_hook_validate |
script |
Validate hook code before saving |
meta_hook_upsert |
id, hook |
Persist hook metadata (validate first!) |
meta_namespace_update |
patch |
Patch the Namespace singleton (incl. MCP flags) |
meta_doctor_run |
— | Run metadata integrity checks |
meta_sync_plan |
items |
Plan a repo↔database metadata sync |
meta_sync_apply |
items, autoApprove |
Apply a reviewed sync plan |
Flow → reference map
| User intent (pt-BR / EN) | Reference |
|---|---|
| Ler metadados, inspecionar esquema, listar metas / read metadata, inspect schema | references/read.md |
| Gerenciar documento, adicionar/remover campo, editar schema / manage document schema, add fields | references/document.md |
| Gerenciar lista, adicionar coluna / manage list, columns | references/list.md |
| Gerenciar formulário/view, visual groups / manage form view | references/view.md |
| Perfil de acesso, permissões, filtros de leitura / access profiles, permissions | references/access.md |
| Relatório pivot, agregações / pivot reports | references/pivot.md |
| Gerar/validar hook, scriptBeforeValidation, validationScript / hooks | references/hook.md |
| Namespace, SMTP, RabbitMQ, habilitar MCP, modo somente leitura / namespace config, MCP flags | references/namespace.md |
| Validar integridade, auditoria de metadados / validate metadata | references/doctor.md |
| Sincronizar metas, deploy de schema / sync metadata repo↔db | references/sync.md |
| Remover módulo meta, excluir documento meta / remove meta module | references/remove.md — MCP gap, read first |
| Descobrir campos de dados / data-side field discovery | references/field-discovery.md |
Guardrails (non-negotiable)
- Upserts replace the whole meta object. Always read the current state first
(
meta_readfor documents; your metadata repo for child metas) and send the complete definition — a partial payload erases what you omit. Exception:meta_namespace_updateis a real patch. - Hooks:
meta_hook_validatebeforemeta_hook_upsert, always. Norequire/import, no comments in hook source (hook.md). - Sync:
meta_sync_planfirst; review with the user; only thenmeta_sync_applywithautoApprove: true— the tool refuses to apply without it. - Full-module removal has no MCP tool. Never improvise REST calls — follow references/remove.md.
_idconventions:Contact(document),Contact:list:Default,Contact:view:Default,Contact:access:Corretor,Contact:pivot:Default,Namespace(singleton). The upsertidargument is this_id.- After metadata changes, offer
meta_doctor_runto check integrity.