Tools reference

The Maetra MCP server exposes a capability-dependent tool set. Call tools/list to discover the tools available to the current workspace and API key.

Invoke a tool with tools/call:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<token from get_mcp_access>",
      "session_ref": "conversation_01JY8Q",
      "action": "Edit the refund approval route"
    }
  }
}

Access preflight#

get_mcp_access

Required first call for every new user turn or work cycle, after context compaction or restart, and whenever Maetra requests an access refresh. No arguments.

The response contains:

{
  "name": "get_mcp_access",
  "arguments": {}
}

Note Every tool below requires an additional string argument, mcp_access_token, containing the current token returned by get_mcp_access.

Task Guard tools#

start_task

Start or transition to the current user-authorized Task Guard task.

After starting, retain task.id, contract_version, and the returned anchor.

get_task_context

Retrieve the active Task Guard contract after turn start, compaction, restart, or when context may be stale.

check_task_alignment

Check a proposed material action against the active task before executing it.

Follow the returned verdict and next_action exactly. See Alignment verdicts.

explain_task_relationship

Provide bounded evidence when check_task_alignment returns NEEDS_EXPLANATION.

The response is a new alignment decision. Follow its verdict.

record_task_progress

Record a compact milestone for the active task.

Check every new_dependencies item with check_task_alignment before acting on it.

record_action_effect

Report what a previously checked action actually changed.

If effect_aligned is false, stop expanding the work and ask the session user inline.

complete_task

Complete the active Task Guard task when the objective and success criteria are satisfied.

Secure tools#

check_action

Scan an AI-agent prompt, tool call, or output with Maetra Secure. Backs POST /v1/secure/scan.

Honor safe, flagged, or blocked before continuing.

list_active_rules

List active Secure rules. No arguments beyond mcp_access_token.

create_rule

Create a Secure rule. New rules default to draft.

update_rule

Update an existing Secure rule by ID. id is required; every create-rule field is optional and only submitted fields change.

Govern tools#

request_approval

Request a Govern checkpoint before a consequential action. Backs POST /v1/checkpoints.

If the response is pending, continue polling with get_approval_status. An approved response is the decision; call authorize_execution immediately before the external action to consume that approval once.

An approved response includes the signed decisionToken, canonical actionEnvelope, actionEnvelopeHash, policyDigest, exact policyVersions, token lifecycle timestamps, and the expected execution and effect deadlines. Maetra carries these fields into the MCP execution tools automatically when you provide the checkpoint ID.

get_approval_status

Long-poll a Govern checkpoint.

Poll until approved, rejected, expired, blocked, or cancelled.

list_active_policies

List active Govern policies, including whether each uses exact rules or decision intelligence. No arguments beyond mcp_access_token.

authorize_execution

Consume an approved decision capability once, immediately before the exact provider request. Maetra reloads the checkpoint, verifies its signed decision and canonical action envelope, and creates a signed execution receipt.

Do not call the provider first. A changed request, wrong executor, expired or revoked decision, or second independent use fails. Provider retries remain possible under the returned executionId.

record_execution_attempt

Append one immutable provider attempt to the authorized execution. Record successes, failures, timeouts, and retries against the same execution_id.

A failed or unknown attempt does not consume another decision. Retry only the identical authorized action, then record the next attempt number.

record_execution_effect

Append the state observed after execution. This connects the approved action and provider attempt to what actually changed.

Self-reported observations remain labelled unverified. Independent verification methods require their configured verifier to validate the proof; the caller cannot turn an unverified observation into a verified receipt by setting a boolean.

Ordering multiple controls#

For the same material action:

1. Call check_task_alignment when Task Guard is enabled.
2. Call check_action before processing untrusted content or executing the tool call.
3. Call request_approval before the external action when Govern is enabled.
4. Poll until the decision is terminal; stop unless it is approved.
5. Call authorize_execution immediately before the exact provider request.
6. Execute only after authorization succeeds, then call record_execution_attempt for every provider attempt.
7. Call record_execution_effect with the resulting observed state.
8. Call record_action_effect when Task Guard effect reporting is enabled.

Task Guard inline confirmation does not replace Govern approval, and Govern approval does not replace one-use execution authorization.