End-to-end example

This page shows the full workflow with every Maetra control enabled. You do not need every step for every integration: Task Guard and Secure are optional, and execution receipts are for teams that want to connect an approval to the exact provider request and observed result.

The example initializes the MCP session, discovers capability-dependent tools, obtains an access token, starts a Task Guard task, checks a material action, runs Secure and Govern, records the result, and completes the task.

Replace https://mcp.maetra.io with your deployed MCP host.

1. Initialize#

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "billing-bot", "version": "0.1.0" }
  }
}

The response includes server instructions for the capabilities enabled in the workspace.

2. Discover tools#

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

The result always includes get_mcp_access, then includes only the Task Guard, Secure, and Govern tools allowed for the current workspace and key.

3. Get capability access#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_mcp_access",
    "arguments": {}
  }
}

Read structuredContent.mcp_access_token, expires_at, and the enabled capabilities. The examples below use <ACCESS_TOKEN> for that short-lived value.

Call get_mcp_access again at the beginning of every new user turn or work cycle.

4. Start the Task Guard task#

If Task Guard is enabled:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "start_task",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "objective": "Process the approved customer refund.",
      "constraints": ["Do not modify unrelated customer records."],
      "success_criteria": ["Refund is processed and recorded."],
      "in_scope": ["Validate refund", "Request approval", "Execute refund"],
      "out_of_scope": ["Change billing provider configuration"],
      "agent_name": "billing-bot",
      "host_type": "CUSTOM_MCP",
      "confirmation_capable": true,
      "effect_reporting_capable": true,
      "idempotency_key": "task-start-01JY8Q"
    }
  }
}

Retain the returned task anchor and contract_version.

5. Check task alignment#

Before the material action:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "action": "Submit a $5,000 refund to the billing provider",
      "action_type": "execute",
      "effect": "TRANSFER",
      "effects": ["Transfer $5,000 to the customer"],
      "tool_name": "billing_api",
      "operation": "create_refund",
      "contract_version": 1,
      "external_action_id": "refund-action-01JY8V",
      "idempotency_key": "alignment-01JY8V",
      "provenance": "HOST_VERIFIED"
    }
  }
}

Proceed only for ALIGNED or SUPPORTING. Explain NEEDS_EXPLANATION, ask the user inline for USER_CONFIRMATION_REQUIRED, refresh context for CONTEXT_REFRESH_REQUIRED, and replan or stop for REFOCUS or STOPPED.

6. Run Secure#

If Secure is enabled, scan the tool call before execution:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "check_action",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "scan_type": "tool_call",
      "tool_name": "billing_api",
      "agent_name": "billing-bot",
      "content": "{\"operation\":\"create_refund\",\"amount\":5000,\"currency\":\"USD\"}"
    }
  }
}

Do not proceed when Secure returns blocked. Review flagged according to your workflow.

7. Request Govern approval#

If Govern is enabled:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "request_approval",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "action": "transfer_funds",
      "agent_name": "billing-bot",
      "autonomy_level": "L3",
      "payload": { "amount": 5000, "currency": "USD", "to": "acct_9931" },
      "target": {
        "type": "customer_account",
        "id": "acct_9931",
        "provider": "northstar-billing"
      },
      "task_authorization": {
        "task_id": "<TASK_ID_FROM_START_TASK>",
        "revision_id": "<ACTIVE_TASK_REVISION_ID>",
        "external_action_id": "refund-action-01JY8V"
      },
      "runtime": {
        "tool_name": "billing_api",
        "tool_version": "4.2.0"
      },
      "executor_audience": "billing-worker",
      "idempotency_key": "refund-checkpoint-01JY8V",
      "reasoning": "Customer refund exceeds the auto-approve limit."
    }
  }
}

If the result is pending, poll:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_approval_status",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "checkpoint_id": "cp_7Yh2Qa",
      "wait_seconds": 30
    }
  }
}

Keep polling until terminal. Stop unless the result is approved. Approval is not the provider call: the next step consumes that approval for one exact execution.

8. Authorize the exact execution#

Immediately before calling the billing provider:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "authorize_execution",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "checkpoint_id": "cp_7Yh2Qa",
      "idempotency_key": "refund-execution-01JY8V",
      "provider": "northstar-billing",
      "operation": "refunds.create",
      "request": {
        "amount": 5000,
        "currency": "USD",
        "customer_account": "acct_9931"
      }
    }
  }
}

Retain the returned executionId. Only now send that exact request to the provider. Repeating this authorization with the same key and identical request returns the existing receipt; changing the request conflicts.

9. Record the provider attempt#

After the provider responds:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "record_execution_attempt",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "execution_id": "exec_01JY91",
      "attempt_number": 1,
      "request": {
        "amount": 5000,
        "currency": "USD",
        "customer_account": "acct_9931"
      },
      "response": {
        "refund_id": "rf_10492",
        "status": "succeeded"
      },
      "status": "succeeded",
      "provider_status": "201",
      "provider_transaction_id": "rf_10492",
      "started_at": "2026-08-12T09:15:02Z",
      "completed_at": "2026-08-12T09:15:03Z"
    }
  }
}

For a timeout or failure, use failed or unknown. An identical provider retry stays under the same execution ID and uses attempt number 2.

10. Record the observed execution effect#

Read the resulting provider or ledger state, then attach it to the same execution:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "record_execution_effect",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "execution_id": "exec_01JY91",
      "observation": {
        "refund_id": "rf_10492",
        "amount": 5000,
        "currency": "USD",
        "status": "succeeded"
      },
      "observed_at": "2026-08-12T09:15:05Z",
      "verification_method": "self_reported",
      "provider": "northstar-billing",
      "external_reference": "rf_10492"
    }
  }
}

This example uses self_reported, so the receipt remains explicitly unverified. Use provider_signed, ledger_readback, or another independent method only when the corresponding proof verifier is configured.

11. Report the effect to Task Guard#

When Task Guard effect reporting is enabled:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "record_action_effect",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "check_id": "tgc_01JY8W",
      "actual_effect": "TRANSFER",
      "actual_effects": ["Transferred $5,000 to customer account acct_9931"],
      "summary": "The approved refund completed successfully.",
      "validation_outcome": "Billing provider returned succeeded."
    }
  }
}

If effect_aligned is false, ask the session user inline before expanding further.

12. Complete the task#

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "complete_task",
    "arguments": {
      "mcp_access_token": "<ACCESS_TOKEN>",
      "session_ref": "conversation_01JY8Q",
      "summary": "The approved refund was processed and recorded.",
      "completion_event_id": "complete-01JY9Z"
    }
  }
}

Batching#

You can batch independent JSON-RPC requests such as initialize and tools/list. Do not batch get_mcp_access with capability calls that need its returned token. Do not batch sequential Task Guard, Secure, Govern, execution, and effect-reporting steps whose inputs or permission depend on the prior result.