Sapiom MCP tools

This is the complete reference for the 20 public tools in @sapiom/[email protected]. Input names, required fields, types, constraints, and descriptions are generated from the package’s runtime tools/list response. Behavior notes are reviewed against the same immutable source.

Authentication labels express Sapiom’s supported product contract: authenticate before every project action, including scaffold, check, Local Run, and local preview configuration. Capability calls are not MCP project tools; real ctx.sapiom.* capability use belongs inside a Sapiom-managed production agent run.

The released inventory still contains three web-app preview tools. They remain listed here so clients can identify every public tool, but their direct hosted sequence is not a supported workflow while it bypasses that agent-run capability boundary. Follow the warning on those entries rather than invoking the sequence.

Result envelope

MCP transports each result as text content. Most tools serialize successful data as formatted JSON. Account and feedback tools can return plain-language text. The released server does not advertise JSON output schemas, so each Returns section names the stable fields or behavior verified in the implementation without inventing a closed response shape. Operational failures set isError: true and normally return:

{
  "error": {
    "code": "<stable-error-class>",
    "message": "<what failed>",
    "hint": "<next action, when available>"
  }
}

An agent execution whose outcome is "failed", or a web-app preview whose status is "failed", can still be a successfully delivered MCP result. Inspect the returned domain status as well as the MCP error flag.

Tool map

Area	Task	Exact tool
Account	Sign in	`sapiom_authenticate`
Account	Check connection state	`sapiom_status`
Account	Sign out	`sapiom_logout`
Agent projects	Create a starter	`sapiom_dev_agents_scaffold`
Agent projects	Validate a project	`sapiom_dev_agents_check`
Agent projects	Test locally	`sapiom_dev_agents_run_local`
Agent projects	Link hosted identity	`sapiom_dev_agents_link`
Agent projects	Clone existing source	`sapiom_dev_agents_clone`
Agent projects	Deploy a build	`sapiom_dev_agents_deploy`
Agent projects	Start a production run	`sapiom_dev_agents_run`
Agent projects	Inspect builds and runs	`sapiom_dev_agents_inspect`
Schedules and signals	Resume a paused run	`sapiom_dev_agents_signal`
Schedules and signals	Create a trigger	`sapiom_dev_agents_schedule`
Schedules and signals	Inspect triggers	`sapiom_dev_agents_schedule_inspect`
Schedules and signals	Cancel a trigger	`sapiom_dev_agents_schedule_cancel`
Schedules and signals	Preview a cadence	`sapiom_dev_agents_cron_preview`
Web-app previews	Configure a preview	`sapiom_dev_sandbox_configure`
Web-app previews	Validate preview configuration	`sapiom_dev_sandbox_check`
Web-app previews	Publish a temporary preview	`sapiom_dev_sandbox_preview`
Feedback	Send product feedback	`sapiom_send_feedback`

Account

`sapiom_authenticate`

Open browser sign-in and cache a Sapiom credential for the selected environment.

Contract	Behavior
Task	Sign in
Authentication	No existing Sapiom session required.
Runs in	Browser sign-in plus a local credential write.
Side effects	May open a browser. Stores the credential in the environment entry in `~/.sapiom/credentials.json`.

Example arguments

{}

Inputs

This tool takes no arguments.

Exact released input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Returns

A plain-language confirmation naming the organization. An already-authenticated response also includes the cached tenant ID.

Expected failures

Browser sign-in times out or is denied.
The callback cannot exchange or store the credential.

Guide: Connect and authenticate

Implementation: packages/mcp/src/tools/authenticate.ts

`sapiom_status`

Report whether the process’s selected Sapiom environment has a cached account credential and which organization it belongs to.

Contract	Behavior
Task	Check connection state
Authentication	No existing Sapiom session required.
Runs in	Read-only local credential lookup.
Side effects	None.

Example arguments

{}

Inputs

This tool takes no arguments.

Exact released input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Returns

Plain-language authentication status; an authenticated result includes organization and tenant identity. The current result does not echo the environment name.

Expected failures

Missing or malformed credential content is reported as not authenticated. An unknown custom environment prevents MCP startup before this tool can run.

Guide: Connect and authenticate

Implementation: packages/mcp/src/tools/status.ts

`sapiom_logout`

Remove the cached Sapiom credential for the selected environment.

Contract	Behavior
Task	Sign out
Authentication	No existing Sapiom session required.
Runs in	Local credential update.
Side effects	Removes only the selected environment’s cached credential; it does not delete projects or hosted agents.

Example arguments

{}

Inputs

This tool takes no arguments.

Exact released input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Returns

A plain-language sign-out confirmation, including when no credential was present.

Expected failures

The local credentials file cannot be updated.

Implementation: packages/mcp/src/tools/status.ts

Agent projects

`sapiom_dev_agents_scaffold`

Create a new TypeScript agent project from a bundled starter.

Contract	Behavior
Task	Create a starter
Authentication	A signed-in Sapiom MCP connection is required by the supported product contract.
Runs in	Local files, npm lookup/install, and local Git initialization.
Side effects	Writes the project, `sapiom.json`, local stubs, and authoring instructions; attempts dependency installation and an initial Git commit on a best-effort basis.

Example arguments

{
  "dir": "./hello-sapiom",
  "template": "default"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	Yes	Target directory for the new project (created if absent; must otherwise be empty, except for Agent Studio’s private .sapiom directory).	minLength `1`
`template`	string	No	Template name. ‘default’ (a minimal two-step starter) or ‘coding-pause’ (the launch + pauseUntilSignal + resume pattern for a non-blocking coding-agent run). Defaults to ‘default’.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "minLength": 1,
      "description": "Target directory for the new project (created if absent; must otherwise be empty, except for Agent Studio's private .sapiom directory)."
    },
    "template": {
      "type": "string",
      "description": "Template name. 'default' (a minimal two-step starter) or 'coding-pause' (the launch + pauseUntilSignal + resume pattern for a non-blocking coding-agent run). Defaults to 'default'."
    }
  },
  "required": [
    "dir"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

targetDir, template, projectName, gitInitialized, and dependenciesInstalled.

Expected failures

The destination contains an entry other than Agent Studio’s reserved .sapiom directory.
The template name is unknown.
Dependency installation can fail softly: the scaffold still succeeds with dependenciesInstalled: false.

Guide: Build your first agent

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_check`

Typecheck, bundle, import, derive, and graph-validate one agent definition.

Contract	Behavior
Task	Validate a project
Authentication	A signed-in Sapiom MCP connection is required by the supported product contract.
Runs in	Local process.
Side effects	Imports author code, so top-level filesystem, process, environment, and network effects remain real.

Example arguments

{
  "dir": "./hello-sapiom"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Agent name, step count, derived manifest, and graph warnings.

Expected failures

Dependencies or TypeScript imports cannot be resolved.
The module exports zero or multiple agent definitions.
The definition, schemas, manifest, or graph is invalid.

Guide: Build and check

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_run_local`

Execute real step code locally while replacing ctx.sapiom.* calls with stubs.

Contract	Behavior
Task	Test locally
Authentication	A signed-in Sapiom MCP connection is required by the supported product contract.
Runs in	Local child process.
Side effects	Creates no Sapiom capability request or capability spend. Author code outside `ctx.sapiom.*` is real and can read, write, launch processes, use the network, or incur third-party charges.

Example arguments

{
  "dir": "./hello-sapiom",
  "input": {
    "name": "Ada"
  }
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`input`	any JSON value	No	The agent’s entry-step input (any JSON value).	—
`stubs`	any JSON value	No	Stub file object: { version, steps: { <step>: { <method.path>: <response> } } }. Each response is returned verbatim; an array is the actual response only for a list-returning method, not a sequence of responses.	—
`maxAttemptsPerStep`	integer	No	Retry cap per step (default 3).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "input": {
      "description": "The agent's entry-step input (any JSON value)."
    },
    "stubs": {
      "description": "Stub file object: { version, steps: { <step>: { <method.path>: <response> } } }. Each response is returned verbatim; an array is the actual response only for a list-returning method, not a sequence of responses."
    },
    "maxAttemptsPerStep": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Retry cap per step (default 3)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

outcome, terminal output or error, ordered step attempts, unusedStubs, and stubWarnings.

Expected failures

Project check/import fails before execution.
Entry input fails its schema.
A step fails or exhausts attempts.
A malformed explicit or file-based stub is rejected.

Guide: Test locally

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_link`

Resolve an organization-owned agent by name and optionally create it, then cache its identity in sapiom.json.

Contract	Behavior
Task	Link hosted identity
Authentication	Required.
Runs in	Sapiom service plus a local configuration write.
Side effects	With `create: true`, may create a hosted agent definition. A successful call writes `definitionId` and name locally.

Example arguments

{
  "dir": "./hello-sapiom",
  "create": true
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`name`	string	No	Agent name (matches defineAgent({ name })). Defaults to the agent’s name read from index.ts.	—
`create`	boolean	No	Create the agent if it does not exist.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "name": {
      "type": "string",
      "description": "Agent name (matches defineAgent({ name })). Defaults to the agent's name read from index.ts."
    },
    "create": {
      "type": "boolean",
      "description": "Create the agent if it does not exist."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

The resolved definitionId and agent name.

Expected failures

No name can be read or supplied.
The named agent does not exist when creation is not requested.
Authentication, authorization, network, or local config writes fail.

Guide: Deploy

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_clone`

Materialize a gallery template, existing fork, or deployed agent source into a local project.

Contract	Behavior
Task	Clone existing source
Authentication	Required.
Runs in	Sapiom repository service, Git, and local files.
Side effects	A template clone creates an organization-owned fork. All modes clone source and write provenance to `sapiom.json`; a definition clone is already linked.

Example arguments

{
  "dir": "./hello-agent",
  "templateId": "hello-agent"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	Yes	Target directory to clone into (created if absent; must otherwise be empty, except for Agent Studio’s private .sapiom directory).	minLength `1`
`templateId`	string	No	Registry template id to fork then clone (e.g. ‘web-research-digest’). Mutually exclusive with forkId and definitionId.	—
`forkId`	string	No	Existing fork id to clone (skips the fork step). Mutually exclusive with templateId and definitionId.	—
`definitionId`	string or number	No	Deployed agent’s definition id to pull local (e.g. from the dashboard URL or a prior link/deploy). Clones the engine’s current build-repo source directly, skipping the fork step, and pre-links the checkout (sapiom.json is written with this id, so sapiom_dev_agents_link is not needed before deploy). Accepts a number or string — the engine id is a bigint. Mutually exclusive with templateId and forkId.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "minLength": 1,
      "description": "Target directory to clone into (created if absent; must otherwise be empty, except for Agent Studio's private .sapiom directory)."
    },
    "templateId": {
      "type": "string",
      "description": "Registry template id to fork then clone (e.g. 'web-research-digest'). Mutually exclusive with forkId and definitionId."
    },
    "forkId": {
      "type": "string",
      "description": "Existing fork id to clone (skips the fork step). Mutually exclusive with templateId and definitionId."
    },
    "definitionId": {
      "type": [
        "string",
        "number"
      ],
      "description": "Deployed agent's definition id to pull local (e.g. from the dashboard URL or a prior link/deploy). Clones the engine's current build-repo source directly, skipping the fork step, and pre-links the checkout (sapiom.json is written with this id, so sapiom_dev_agents_link is not needed before deploy). Accepts a number or string — the engine id is a bigint. Mutually exclusive with templateId and forkId."
    }
  },
  "required": [
    "dir"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Clone destination and provenance, plus definitionId when cloning a deployed agent; the tool also returns a next-step hint.

Expected failures

Not exactly one of templateId, forkId, or definitionId is supplied.
The destination is not scaffoldable.
Forking, credential minting, Git clone, or config writing fails.

Guide: Create from a template

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_deploy`

Package the current working tree, start a metered cloud build, and wait for its terminal build state.

Contract	Behavior
Task	Deploy a build
Authentication	Required.
Runs in	Local bundle and Git synthesis, then Sapiom build infrastructure.
Side effects	Uploads reachable local source, including uncommitted edits, and creates an immutable build. It does not start an agent execution.

Example arguments

{
  "dir": "./hello-sapiom"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`branch`	string	No	Branch to push to (default ‘main’).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "branch": {
      "type": "string",
      "description": "Branch to push to (default 'main')."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Build identity and terminal build status, including buildRunId.

Expected failures

The project is unlinked or its config is invalid.
The directory is not a Git repository with a commit.
Bundling, upload, build, authentication, or authorization fails.
The local wait can time out even while the remote build continues.

Guide: Deploy

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_run`

Start a real execution of the linked agent’s runnable build.

Contract	Behavior
Task	Start a production run
Authentication	Required.
Runs in	Sapiom-managed agent runtime.
Side effects	Creates a production execution and can create metered capability usage inside that run.

Example arguments

{
  "dir": "./hello-sapiom",
  "input": {
    "name": "Ada"
  }
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`input`	any JSON value	No	The agent’s entry-step input (any JSON value).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "input": {
      "description": "The agent's entry-step input (any JSON value)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

executionId, start metadata, and a dashboard webappUrl; this is a start receipt, not terminal output.

Expected failures

The project is unlinked.
No runnable build is available.
Input fails the agent’s entry schema.
Authentication, authorization, quota, or service availability blocks the start.

Guide: Run in production

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_inspect`

List recent executions, inspect one execution, or inspect a build; optionally wait for a run to settle.

Contract	Behavior
Task	Inspect builds and runs
Authentication	Required.
Runs in	Read-only Sapiom service calls.
Side effects	No hosted state change. `wait: true` performs bounded polling for up to 55 seconds.

Example arguments

{
  "executionId": "<execution-id>",
  "wait": true
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (for build inspection, which needs the linked id).	—
`executionId`	string	No	Execution to inspect.	—
`buildRunId`	string	No	Build to inspect (requires a linked project).	—
`step`	string or number	No	Expand one step’s heavy fields: its stepName or stepOrder (from the compact step list). Pair with `include` to choose which fields.	—
`attempt`	integer	No	Restrict expansion to a single attempt of the selected `step` (a retried step has several). Omit to expand every attempt of that step.	—
`include`	array	No	Heavy step fields to expand for the selected `step`: ‘input’ \| ‘output’ \| ‘logs’ \| ‘events’ \| ‘sharedState’ \| ‘error’. Ignored without `step`. Each is capped to the char budget.	—
`wait`	boolean	No	When inspecting an executionId, block until it reaches a terminal state (or settles on a pause needing a signal) instead of returning the current snapshot. Lets the tool own the polling so you don’t have to.	—
`maxWaitSeconds`	number	No	Max seconds to wait when wait:true (default 45, capped at 55). On timeout it returns the latest snapshot with waiting:true — call again to keep waiting.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (for build inspection, which needs the linked id)."
    },
    "executionId": {
      "type": "string",
      "description": "Execution to inspect."
    },
    "buildRunId": {
      "type": "string",
      "description": "Build to inspect (requires a linked project)."
    },
    "step": {
      "type": [
        "string",
        "number"
      ],
      "description": "Expand one step's heavy fields: its stepName or stepOrder (from the compact step list). Pair with `include` to choose which fields."
    },
    "attempt": {
      "type": "integer",
      "description": "Restrict expansion to a single attempt of the selected `step` (a retried step has several). Omit to expand every attempt of that step."
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "input",
          "output",
          "logs",
          "events",
          "sharedState",
          "error"
        ]
      },
      "description": "Heavy step fields to expand for the selected `step`: 'input' | 'output' | 'logs' | 'events' | 'sharedState' | 'error'. Ignored without `step`. Each is capped to the char budget."
    },
    "wait": {
      "type": "boolean",
      "description": "When inspecting an executionId, block until it reaches a terminal state (or settles on a pause needing a signal) instead of returning the current snapshot. Lets the tool own the polling so you don't have to."
    },
    "maxWaitSeconds": {
      "type": "number",
      "description": "Max seconds to wait when wait:true (default 45, capped at 55). On timeout it returns the latest snapshot with waiting:true — call again to keep waiting."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Recent executions when no identity is supplied.
A compact execution plus webappUrl by default; select step and include to retrieve bounded heavy fields.
Build state when buildRunId is supplied with a linked project.

Expected failures

Build inspection is requested without a linked project configuration.
The execution, build, or linked definition cannot be found or accessed.
A selected step, attempt, or included field is invalid.

Guide: Inspect

Implementation: packages/mcp/src/tools/agents.ts

Schedules and signals

`sapiom_dev_agents_signal`

Deliver a named signal to the matching correlation ID in one paused execution.

Contract	Behavior
Task	Resume a paused run
Authentication	Required.
Runs in	Sapiom-managed agent runtime.
Side effects	Can resume one or more matching waits in a production execution. Reusing a signal identity can produce no match or duplicate-delivery evidence.

Example arguments

{
  "executionId": "<execution-id>",
  "name": "approval",
  "correlationId": "request-123",
  "payload": {
    "approved": true
  }
}

Inputs

Field	Type	Required	Description	Constraints
`executionId`	string	Yes	The paused execution.	—
`name`	string	Yes	Signal name to deliver.	—
`correlationId`	string	Yes	Signal correlation id.	—
`payload`	any JSON value	No	Signal payload (any JSON value).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "executionId": {
      "type": "string",
      "description": "The paused execution."
    },
    "name": {
      "type": "string",
      "description": "Signal name to deliver."
    },
    "correlationId": {
      "type": "string",
      "description": "Signal correlation id."
    },
    "payload": {
      "description": "Signal payload (any JSON value)."
    }
  },
  "required": [
    "executionId",
    "name",
    "correlationId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Signal delivery result, including the number of matching waits. A zero match count is a delivered no-op, not necessarily an MCP failure.

Expected failures

The execution is not accessible.
Payload shape is invalid for the waiting step.

Guide: Use signals

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_schedule`

Create a recurring cron trigger or a one-off delayed run for a deployed agent.

Contract	Behavior
Task	Create a trigger
Authentication	Required.
Runs in	Sapiom scheduler.
Side effects	Creates a schedule that can start future production executions.

Example arguments

{
  "definition": "hello-sapiom",
  "kind": "schedule_cron",
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "input": {}
}

Inputs

Field	Type	Required	Description	Constraints
`definition`	string	Yes	The agent’s tenant-unique slug (the handle it was deployed under).	—
`kind`	string	Yes	’schedule_cron’ = recurring; ‘schedule_once’ = a single delayed run.	one of `"schedule_cron"`, `"schedule_once"`
`cron`	string	No	Cron expression — required for ‘schedule_cron’. E.g. ‘0 9 * * 1-5’ = 9am on weekdays.	—
`timezone`	string	No	IANA timezone the cron runs in (e.g. ‘America/New_York’). Defaults to UTC.	—
`at`	string	No	ISO 8601 fire time — required for ‘schedule_once’. E.g. ‘2026-07-01T17:00:00Z’.	—
`input`	any JSON value	No	Execution input passed to each run (any JSON value).	—
`startAt`	string	No	Cron only: ISO time before which no occurrence fires.	—
`endAt`	string	No	Cron only: ISO time after which the schedule completes.	—
`policy`	any JSON value	No	Cron only: { catchupPolicy?: ‘skip’\|‘all’, overlapPolicy?: ‘allow’, jitterMs?: number }.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "definition": {
      "type": "string",
      "description": "The agent's tenant-unique slug (the handle it was deployed under)."
    },
    "kind": {
      "type": "string",
      "enum": [
        "schedule_cron",
        "schedule_once"
      ],
      "description": "'schedule_cron' = recurring; 'schedule_once' = a single delayed run."
    },
    "cron": {
      "type": "string",
      "description": "Cron expression — required for 'schedule_cron'. E.g. '0 9 * * 1-5' = 9am on weekdays."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone the cron runs in (e.g. 'America/New_York'). Defaults to UTC."
    },
    "at": {
      "type": "string",
      "description": "ISO 8601 fire time — required for 'schedule_once'. E.g. '2026-07-01T17:00:00Z'."
    },
    "input": {
      "description": "Execution input passed to each run (any JSON value)."
    },
    "startAt": {
      "type": "string",
      "description": "Cron only: ISO time before which no occurrence fires."
    },
    "endAt": {
      "type": "string",
      "description": "Cron only: ISO time after which the schedule completes."
    },
    "policy": {
      "description": "Cron only: { catchupPolicy?: 'skip'|'all', overlapPolicy?: 'allow', jitterMs?: number }."
    }
  },
  "required": [
    "definition",
    "kind"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

The schedule configuration, status, next fire time, and a health hint when available.

Expected failures

The agent slug does not identify an accessible deployed agent.
Required fields do not match kind.
Cron, timezone, time bounds, or policy is invalid.

Guide: Schedule

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_schedule_inspect`

List one agent’s schedules or inspect one schedule and its recent fires.

Contract	Behavior
Task	Inspect triggers
Authentication	Required.
Runs in	Read-only Sapiom scheduler calls.
Side effects	None.

Example arguments

{
  "definition": "hello-sapiom",
  "status": "active"
}

Inputs

Field	Type	Required	Description	Constraints
`scheduleId`	string	No	Inspect one schedule (detail + recent fires + a health hint).	—
`definition`	string	No	List schedules for this agent slug (used when scheduleId is omitted).	—
`status`	string	No	Filter the list by status.	one of `"active"`, `"paused"`, `"completed"`, `"disabled"`

Exact released input schema

{
  "type": "object",
  "properties": {
    "scheduleId": {
      "type": "string",
      "description": "Inspect one schedule (detail + recent fires + a health hint)."
    },
    "definition": {
      "type": "string",
      "description": "List schedules for this agent slug (used when scheduleId is omitted)."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "completed",
        "disabled"
      ],
      "description": "Filter the list by status."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

A schedule with recent fires and a health hint when scheduleId is supplied, or a filtered schedule list when definition is supplied.

Expected failures

Neither scheduleId nor definition is supplied.
The schedule or agent is missing or inaccessible.
The status filter is invalid.

Guide: Schedule

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_schedule_cancel`

Disable all future fires for one schedule.

Contract	Behavior
Task	Cancel a trigger
Authentication	Required.
Runs in	Sapiom scheduler.
Side effects	Irreversibly disables future occurrences. It does not cancel an execution that already started.

Example arguments

{
  "scheduleId": "<schedule-id>"
}

Inputs

Field	Type	Required	Description	Constraints
`scheduleId`	string	Yes	The schedule to cancel.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "scheduleId": {
      "type": "string",
      "description": "The schedule to cancel."
    }
  },
  "required": [
    "scheduleId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

The cancelled schedule’s resulting state.

Expected failures

The schedule is missing or inaccessible, or authentication, authorization, or service availability blocks cancellation.

Guide: Schedule

Implementation: packages/mcp/src/tools/agents.ts

`sapiom_dev_agents_cron_preview`

Validate a cron expression and calculate upcoming UTC occurrences without creating a schedule.

Contract	Behavior
Task	Preview a cadence
Authentication	Required.
Runs in	Read-only Sapiom scheduler calculation.
Side effects	None; no schedule is created.

Example arguments

{
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "count": 5
}

Inputs

Field	Type	Required	Description	Constraints
`cron`	string	Yes	Cron expression to validate, e.g. ‘0 9 * * 1-5’.	—
`timezone`	string	No	IANA timezone (default UTC).	—
`count`	number	No	How many upcoming occurrences to return (default 5).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "cron": {
      "type": "string",
      "description": "Cron expression to validate, e.g. '0 9 * * 1-5'."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone (default UTC)."
    },
    "count": {
      "type": "number",
      "description": "How many upcoming occurrences to return (default 5)."
    }
  },
  "required": [
    "cron"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

Validated cron and timezone information plus the requested upcoming occurrences.

Expected failures

Cron syntax, timezone, or occurrence count is invalid.

Guide: Schedule

Implementation: packages/mcp/src/tools/agents.ts

Web-app previews

`sapiom_dev_sandbox_configure`

Identify or inspect the released local configuration step for web-app previews. The direct preview sequence is not a supported public workflow while its hosted execution bypasses the agent-run capability boundary.

Contract	Behavior
Task	Configure a preview
Authentication	A signed-in Sapiom MCP connection is required by the supported product contract.
Runs in	Local configuration write.
Side effects	Writes `resources.<name>` in `sapiom.json`; it does not deploy anything. Do not treat this as approval to continue into direct hosted preview execution.

Example arguments

{
  "dir": "./web-app",
  "name": "web",
  "source": {
    "kind": "upload",
    "path": "."
  },
  "start": "npm run start",
  "port": 3000
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`name`	string	Yes	Resource name — the sapiom.json `resources` key and the sandbox name (e.g. `web`).	—
`source`	object	Yes	—	See exact schema below.
`build`	string	No	—	—
`start`	string	Yes	—	minLength `1`
`port`	integer	Yes	—	minimum `1`; maximum `65535`
`tier`	string	No	—	one of `"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`
`ttl`	string	No	—	—
`env`	object	No	—	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "name": {
      "type": "string",
      "description": "Resource name — the sapiom.json `resources` key and the sandbox name (e.g. `web`)."
    },
    "source": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "upload"
            },
            "path": {
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "git"
            },
            "slug": {
              "type": "string",
              "minLength": 1
            },
            "path": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "slug"
          ],
          "additionalProperties": false
        }
      ]
    },
    "build": {
      "type": "string"
    },
    "start": {
      "type": "string",
      "minLength": 1
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535
    },
    "tier": {
      "type": "string",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ]
    },
    "ttl": {
      "type": "string"
    },
    "env": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "name",
    "source",
    "start",
    "port"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

The validated stored preview configuration.

Expected failures

sapiom.json is missing or invalid.
The source, commands, port, tier, TTL, or environment map fails validation.

Implementation: packages/mcp/src/tools/sandbox.ts

`sapiom_dev_sandbox_check`

Identify or inspect the released validation step for web-app previews. The direct preview sequence is not a supported public workflow while its hosted execution bypasses the agent-run capability boundary.

Contract	Behavior
Task	Validate preview configuration
Authentication	A signed-in Sapiom MCP connection is required by the supported product contract.
Runs in	Local configuration read and validation.
Side effects	None.

Example arguments

{
  "dir": "./web-app"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

ok, normalized sandboxes, and actionable issues.

Expected failures

The project configuration cannot be read or parsed.

Implementation: packages/mcp/src/tools/sandbox.ts

`sapiom_dev_sandbox_preview`

The released package can upload, build, start, and expose a configured web app, but this direct hosted action is not a supported public workflow because it bypasses the agent-run capability boundary.

Contract	Behavior
Task	Publish a temporary preview
Authentication	Required.
Runs in	Sapiom preview infrastructure.
Side effects	May provision preview infrastructure, upload local code, run build/start commands, and expose a public URL. Do not invoke it until the product aligns preview execution with the approved agent-run-only capability boundary.

Example arguments

{
  "dir": "./web-app",
  "name": "web"
}

Inputs

Field	Type	Required	Description	Constraints
`dir`	string	No	Project directory (defaults to the current working directory).	—
`name`	string	No	Which sandbox to deploy, when the project defines more than one.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "dir": {
      "type": "string",
      "description": "Project directory (defaults to the current working directory)."
    },
    "name": {
      "type": "string",
      "description": "Which sandbox to deploy, when the project defines more than one."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

name, url, status, and logs. A failed status with logs is a successful tool response, not necessarily an MCP error.

Expected failures

Configuration is missing or ambiguous.
Authentication, provisioning, upload, build, or start fails.
Build/start failure can be represented by status: "failed"; inspect the returned logs.

Implementation: packages/mcp/src/tools/sandbox.ts

Feedback

`sapiom_send_feedback`

Send user-approved, plain-language product feedback to the Sapiom team.

Contract	Behavior
Task	Send product feedback
Authentication	Required.
Runs in	Sapiom feedback service.
Side effects	Creates a feedback record. `message` and `context` are also included in MCP tool-call analytics; confirm the wording and never include code, files, logs, environment variables, keys, tokens, or other secrets.

Example arguments

{
  "message": "The deploy error should identify the failing build stage.",
  "context": "Deploying an agent after Local Run passed."
}

Inputs

Field	Type	Required	Description	Constraints
`message`	string	Yes	The user’s feedback in their own words: what’s wrong, what they expected, or what they want. Plain language only — no code, logs, stack traces, or secrets.	minLength `1`
`context`	string	No	Optional one- or two-sentence plain-language summary of what the user was doing when the feedback came up (e.g. “deploying an agent after run_local passed”). Never include file contents, code snippets, logs, stack traces, environment variables, API keys, or tokens.	—

Exact released input schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "description": "The user's feedback in their own words: what's wrong, what they expected, or what they want. Plain language only — no code, logs, stack traces, or secrets."
    },
    "context": {
      "type": "string",
      "description": "Optional one- or two-sentence plain-language summary of what the user was doing when the feedback came up (e.g. \"deploying an agent after run_local passed\"). Never include file contents, code snippets, logs, stack traces, environment variables, API keys, or tokens."
    }
  },
  "required": [
    "message"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns

A plain-language receipt, with a reference ID when the service returns one.

Expected failures

The message is empty.
Authentication, authorization, network, or service submission fails.

Implementation: packages/mcp/src/tools/feedback.ts