Before you start
Publish a self-describing contract
An external caller sees the published contract, not the handler. Explain when to use the action, its business terms and relationships, prerequisites, create/update semantics, consequential effects, and what success means. Put field guidance in property descriptions and operation guidance beside its alternative. Use a typed output to explain identifiers, results, freshness, and completeness where relevant.
Declare known fields, enum values, required fields, scalar bounds, and array limits in the schema. A field omitted from required is optional; accepting null is a separate type declaration. Defaults are descriptive and are not inserted into input. Avoid open payloads when the accepted shape is known. Reuse schema definitions for discovery and handler validation where practical, and test business rules against those contracts.
For several operations, use oneOf with a required constant selector such as op. Exactly one alternative must match (including its operation-specific required fields). Each oneOf permits at most 32 alternatives, with a shared schema budget of 500 nodes and depth 12. Regex patterns, references, formats, and other composition keywords remain unsupported; validate normalization, formats, live relationships, permissions, and state transitions in bounded handler code.
Supply examples on input/output schemas and fields. Save and publication check each supplied example against its schema without running the handler. Each examples array permits up to 10 values, with at most 50 examples per input or output contract. These example checks gate authoring; invocation validates actual input and output without rechecking example values or counts. Schema-valid examples do not prove business execution succeeds. Test the handler against representative valid, rejected, and stale-version requests before publication.
Schema-invalid input is rejected before action execution. validation_failed details identify path, rule, and schemaPath, with allowedValues or constraint when available. Compound failures may include bounded issues; truncation flags signal omitted diagnostics. These errors contain no submitted values. Current permissions and live business rules still apply at execution.
API and SDK discovery select the current published action revision. App MCP discovery selects permitted app bindings and their pinned revisions; app publication and action publication are separate. Descriptions do not grant authority, and declared capabilities do not predict the exact records an invocation will affect.
const inputSchema = {
type: 'object',
description: 'Create an item or archive an existing item using its current version.',
oneOf: [
{
type: 'object',
properties: {
op: { const: 'create' },
name: { type: 'string', minLength: 1, description: 'Name of the new item.' },
priority: { type: 'string', enum: ['low', 'high'], examples: ['low'] },
},
required: ['op', 'name', 'priority'],
additionalProperties: false,
},
{
type: 'object',
properties: {
op: { const: 'archive' },
id: { type: 'string', minLength: 1 },
expectedVersion: { type: 'string', minLength: 1, description: 'Version from the latest record read.' },
},
required: ['op', 'id', 'expectedVersion'],
additionalProperties: false,
},
],
examples: [{ op: 'create', name: 'Example item', priority: 'low' }],
};Expose actions as native MCP tools
An app MCP connector exposes published actions bound to the app that both the app and the signed-in user can run. To customize a tool, add tool metadata to the action definition, publish it, and bind that revision to the app. Without metadata, Permute uses the action name and schemas and derives hints from the pinned revision’s capabilities. Actions limited to managed database and warehouse reads are read-only and closed-world. Writable managed tables are potentially destructive and closed-world. Connector or SDK calls default to potentially destructive and open-world. The fallback idempotentHint is always false.
tool.name starts with a lowercase letter, uses lowercase letters, digits, or underscores, and has at most 40 characters. Describe the business operation and consequential effects in tool.description. Permute generates the full MCP tool name from the operation name and an identity tied to the app, action, and pinned action revision. It exposes the action schemas and approval hints to the client.
Set readOnlyHint only for reads without business-state changes, and destructiveHint for deletion, overwriting, or irreversible sends. Additive writes set both false. Idempotence and open-world access are independent: a private workspace is not open-world just because it is remote. Hints must describe all branches. Validation rejects contradictory read-only/destructive flags. Publishers must describe actual behavior, including connector and SDK calls; annotations do not narrow declared capabilities or grant permissions.
The coding agent or developer authoring the action owns these labels. Inspect every branch and connector/SDK call, and reassess the description and all four hints whenever code, bindings, or accepted operations change. Save metadata with the changed code. If effects are uncertain, use readOnlyHint false, destructiveHint true, idempotentHint false, and openWorldHint true until actual behavior is established. Permute validates shape and consistency; it does not infer risk from code or perform an automated security assessment.
MCP action tools execute directly; the client controls confirmation. Calls accept requestId and input and use server-selected revision pins. Use the same request identity and input for retries. Apps can bind up to 500 actions; native discovery is paginated, and supporting hosts load definitions on demand. An action grant does not grant source read access.
// Definition fragment for an action whose handler actually archives a contact.
// Save it with the reviewed handler, inputSchema, and outputSchema.
const tool = {
name: 'archive_contact',
description: 'Archive a contact using its verified ID and current version.',
annotations: {
readOnlyHint: false,
destructiveHint: true,
idempotentHint: true,
openWorldHint: false,
},
};Keep published actions backward compatible
Treat the published action as an interface that existing callers may keep using after an update (MCP clients can retain tool names, schemas, and approval hints). For a routine fix, keep the action ID, operation name, and behavior callers depend on. Set an explicit tool.name for a stable operation name if you plan to edit the action’s display name.
Keep old inputs valid and preserve their meaning. For example, add an optional note to save_task and preserve the old behavior when note is omitted. Keep existing output fields, types, and meanings. An added field can break a client whose cached output schema sets additionalProperties to false. Keep the old result shape if callers still depend on it.
Give a breaking operation its own action and tool name. For example, publish archive_contact separately from a tool that only updates contact details. Keep the old action bound during migration where it remains appropriate and authorized. Always update approval hints to reflect actual effects, even if that means clients need to refresh before using the changed action.
Before publishing, replay requests from the current release against the candidate and check that its results fit the old output contract. To test MCP, connect to a test app before the update. After updating it, call the old tool name with the old input and a fresh requestId from the same session. Use test data for writes and verify the recorded outcome. Permute can route a verified older tool name to the live action, which validates input and enforces current permissions.