MCP server

The Pikbase MCP server lets compatible AI clients discover and invoke the same governed tool contracts available through the CLI. The registry, risk classification, and approval rules are shared — only the transport differs.

Start the server

gsb mcp -y

Configure your MCP client to launch that command in an environment where the CLI has been initialized for the intended tenant. Keep credentials out of committed client configuration.

Risk classification

Every tool carries a risk level that decides whether it is enabled by default.

Risk	Enabled by default	Approval
read	Yes	Never required
write	No	Required
destructive	No	Required
external-side-effect	No	Required

Read tools are the only ones an agent can invoke unattended.

Read tools

Tool	Input	Returns
getById	{ definitionType, id }	One entity
getCopy	{ request }	A detached copy of an entity
query	{ queryParams }	A page of entities
queryMapped	{ queryParams }	A page of mapped entities
getEntityDef	{ entityDef }	One entity definition
queryEntityDefs	{ searchTerm, page, pageSize, includeSystem }	{ entityDefs, totalCount }
getCommonPropertyDefs	{}	Available property data types

Bounded inspection tools

Inspection tools page their results and cite the artifact they read, so an agent cannot pull an unbounded payload into context.

Tool	Input	Returns
inspectSchema	{ searchTerm, page, pageSize, includeSystem }	Paged definitions with a cited artifact
inspectQuery	{ queryParams, page, pageSize }	A bounded page of entities
inspectLogs	{ queryParams, page, pageSize }	A bounded page of log rows
inspectDocs	{ methodName }	Operation documentation
inspectSchemaDocs	{}	Schema management documentation

page defaults to 1 and pageSize to 25.

Documentation tools

Tool	Input
getDocs	{ "methodName": "query" }
getApiDocs	{}
getSchemaDocs	{}
getServerlessFunctionDocs	{}
getSchemaManagerDocs	{}

Write tools

Disabled by default; each needs explicit approval.

Tool	Input
save	{ request }
saveMulti	{ request }
saveMappedItems	{ request }
removeMappedItems	{ request }
createEntityDef	{ entityDef }
updateEntityDef	{ entityDef }
createOrUpdateSchema	{ entityDefs }
addProperty	{ property, entityDef }
updateProperty	{ property, entityDef }
removeProperty	{ property, entityDef }

Cache consistency after schema changes

Routine schema work, such as creating one definition or adding a column, updates the affected caches automatically. Do not clean caches after every MCP schema mutation.

After an approved large migration or mass entity-definition update, an operator should run gsb --tenant <tenantCode> cache clean before validation. Cache cleaning is intentionally not an unattended MCP tool. Verify representative definitions and queries through the normal load-balanced endpoint afterward; repeat the clean or escalate if cluster nodes still disagree.

Destructive tools

Tool	Input
delete	{ request, confirm, confirmationToken }
deleteQuery	{ queryParams, confirm, confirmationToken }

Both use a two-step handshake. The first call returns a confirmationToken bound to the exact payload and tenant; the second repeats the identical payload with confirm: true. Changing any field invalidates the token, and each token is consumed on use.

External side-effect tools

Tool	Input
runWfFunction	{ request }
testWfFunction	{ request }
runWorkflow	{ request }
startWorkflow	{ request }
iterateTask	{ request }

These reach systems outside the tenant database. Treat them as irreversible.

Agent safety

Treat model output as untrusted input. Keep tools permission-scoped, meter costly operations per tenant, and require explicit human confirmation before any generated mutation that can remove or overwrite data.