MCP tools

Vector exposes the admin to AI agents over the Model Context Protocol, through kinetis/mcp. The tools call the same services and policies as the REST API: an agent sees what its identity may see, and every write is validated, hooked and audited.

Tool

Arguments

Does

vector_resources

—

Lists the resources this identity may view: slug, label and group.

vector_describe

resource

Describes one resource’s fields, actions and permissions (below).

vector_query

resource, filter, q, sort, page, perPage

Lists records under the list grammar. perPage defaults to 25 and is capped at 200 and at the resource’s own maximum.

vector_get

resource, id

Reads one record, with its permissions.

vector_create

resource, values

Creates a record, validated as the form validates it.

vector_update

resource, id, values, version

Updates the fields in values. Pass the version you read to refuse a stale write.

vector_delete

resource, id, force

Deletes a record; on a soft-deleting resource it goes to the trash unless force is true.

vector_run_action

resource, action, ids, values

Runs an action on record ids (none for a standalone action) with its dialog values. A download comes back base64-encoded, with its filename and content type.

vector_widget

widget, dashboard or resource, range

Computes a dashboard widget (dashboard defaults to main) or a resource widget, for a range such as 30d.

An agent lists the resources, then describes the one it works with, so its context holds one resource’s detail rather than all of them. For each field, vector_describe (Kinetis\Vector\Mcp\ResourceDescription) states:

  • writable: whether a create, an update, both or neither may write it.

  • required: whether a create must send it. It follows the writer’s own rule, so a create with just the required fields succeeds.

  • rules, options, default, unique: what a value must satisfy.

  • format: what a value looks like, where the type alone doesn’t say (a date, a rich-text document, a list of ids).

  • relation: the resource it points to.

  • filter, sortable, searchable: what vector_query accepts for it.

  • visibleWhen, requiredWhen, disabledWhen: when these depend on other fields’ values.

The description also carries each action with its dialog fields, and what this identity may do. It is in the identity’s language, and a field a policy hides is left out. Files and images can’t be uploaded through the tools.

The resource vector://schema is the whole descriptor, as this identity sees it.

values (on create, update and run-action) is a JSON object of field values, as a REST write takes them. filter (on query) is the list grammar’s filter as a JSON object: {field: value | {op: value}, or: [filter, ...], and: [filter, ...]}.

Serving them

  • Over HTTP, at POST /mcp: your authentication middleware joins the mcp group, as it joins vector (Authentication).

  • Over stdio, with kinetis mcp:serve: the tools inject CurrentUserInterface, so without an authenticated identity they fail closed. The HTTP mcp group does not run over stdio.

Either way, the tools ask VectorAccessInterface whether the identity may use the admin at all, as the vector group does for the UI.

When POST /mcp answers 401

If every caller of POST /mcp gets 401 Unauthenticated. while the same token works on /vector/…, your authentication middleware is in the vector group but not the mcp group. Add it there, at a priority above the identity guard’s, as the mcp middleware group shows, and rebuild the compiled cache in production (Deployment).

Warning

Do not set MCP_HTTP_PUBLIC=true to make the 401 go away. It lets requests without an identity through to every tool: any tool of yours that needs no identity becomes public, and Vector’s tools still have no identity to run as.

See also