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:

Field	Description
`workspace`	Workspace ID, MCP enabled state, and configuration version.
`capabilities`	Enabled state, reason, and allowed tools for Secure, Govern, and Task Guard.
`required_behavior`	Runtime instructions the host must follow.
`mcp_access_token`	Short-lived token required by every capability tool.
`expires_at`	Access-token expiry.

{
  "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.

Argument	Type	Required	Description
`session_ref`	string	✓	Stable host conversation or session reference.
`objective`	string	✓	The direct user's current objective.
`idempotency_key`	string	✓	Stable retry key for the task start.
`title`	string		Short task title.
`agent_name` / `agent_id`	string		Agent identity.
`constraints`, `decisions`	string[]		User constraints and agreed decisions.
`success_criteria`	string[]		Observable completion conditions.
`in_scope`, `out_of_scope`	string[]		Explicit task boundaries.
`open_questions`	string[]		Unresolved questions.
`direct_user_event_id`	string		Required for a later task or contract revision in the same session.
`host_type`	string		`CODEX`, `CLAUDE`, `CUSTOM_MCP`, or `CUSTOM_API`.
`integration_mode`	string		`ADVISORY` or `ENFORCED`.
`confirmation_capable`	boolean		Whether the host can ask the session user inline.
`effect_reporting_capable`	boolean		Whether the host can report actual effects.

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.

Argument	Type	Required
`session_ref`	string	✓

check_task_alignment

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

Argument	Type	Required	Description
`session_ref`	string	✓	Stable session reference.
`action`	string	✓	Concise proposed action.
`action_type`	string		Category such as `edit`, `read`, `send`, `create`, or `execute`.
`target`	string		File, system, person, artifact, or other target.
`effects`	string[]		Expected direct and connected effects.
`rationale`	string		Why the action supports the task.
`current_step`	string		Current task step.
`contract_version`	number		Last contract version fetched by the host.
`external_action_id`	string		Stable host action ID used to bind effect reporting.
`idempotency_key`	string		Stable retry key.
`effect`	string		`READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`, or `OTHER`.
`tool_name`, `operation`	string		Tool and operation being checked.
`resource`, `destination`	object		Structured target and destination metadata.
`data_classes`	string[]		Data classifications involved.
`reversible`	boolean		Whether the action can be undone.
`estimated_cost`	number		Estimated monetary cost.
`provenance`	string		`HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`, or `UNVERIFIED`.
`claimed_relationship`	string		The agent's claimed relationship to the task.

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

explain_task_relationship

Provide bounded evidence when check_task_alignment returns NEEDS_EXPLANATION.

Argument	Type	Required
`check_id`	string	✓
`relationship`	string	✓
`evidence`	string[]

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

record_task_progress

Record a compact milestone for the active task.

Argument	Type	Required
`session_ref`	string	✓
`summary`	string	✓
`idempotency_key`	string	✓
`completed`, `next_steps`	string[]
`new_dependencies`, `open_questions`	string[]
`current_step`	string

Check every new_dependencies item with check_task_alignment before acting on it.

record_action_effect

Report what a previously checked action actually changed.

Argument	Type	Required
`check_id`	string	✓
`actual_effects`	string[]	✓
`actual_effect`	string
`affected_resources`	object[]
`result_reference`, `artifact_hash`	string
`summary`, `validation_outcome`	string

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.

Argument	Type	Required
`session_ref`	string	✓
`summary`	string	✓
`completion_event_id`	string	✓

Secure tools#

check_action

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

Argument	Type	Required	Description
`content`	string	✓	Prompt, tool payload, or output to scan.
`scan_type`	string		`prompt_input` (default), `tool_call`, or `output`.
`tool_name`	string	✓ if `tool_call`	Tool being called.
`agent_id`, `agent_name`	string		Agent identity.
`context`	object		Structured context.

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.

Argument	Type	Required	Description
`name`	string	✓	Rule name.
`type`	string	✓	`data_pattern`, `policy_dsl`, `prompt_pattern`, or `tool_call`.
`action`	string		`block`, `flag`, or `log`.
`severity`	string		`critical`, `high`, `medium`, or `low`.
`status`	string		`active`, `archived`, or `draft`.
`applies_to_all`	boolean		Defaults to `true`.
`data_direction`	string		`inbound`, `outbound`, or `both`.
`custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids`	string[]		Rule-specific values.

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.

Argument	Type	Required	Description
`action`	string	✓	Action name.
`payload`	object		Structured action details.
`agent_id`, `agent_name`	string		Agent identity.
`context`, `reasoning`	string		Reviewer context and agent reasoning.
`autonomy_level`	string		`L0`–`L5`.
`policy_ids`, `policy_group_ids`	string[]		Restrict evaluation.
`timeout_seconds`	number		Wall-clock ceiling for a human decision.

If the response is pending, continue polling with get_approval_status. Proceed only after approved.

get_approval_status

Long-poll a Govern checkpoint.

Argument	Type	Required
`checkpoint_id`	string	✓
`wait_seconds`	number

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.

Ordering multiple controls#

For the same material action:

Call check_task_alignment when Task Guard is enabled.
Call check_action before processing untrusted content or executing the tool call.
Call request_approval before the external action when Govern is enabled.
Execute only after every enabled control permits it.
Call record_action_effect after execution when Task Guard effect reporting is enabled.

Task Guard inline confirmation does not replace Govern approval.