Ejemplo final a final

Esta página muestra el flujo de trabajo completo con cada control de Maetra habilitado. Usted no necesita cada paso para cada integración: Task Guard y Secure son opcionales, y los recibos de ejecución son para equipos que quieren conectar una aprobación a la solicitud exacta del proveedor y el resultado observado.

El ejemplo inicializa la sesión de MCP, descubre herramientas dependientes de la capacidad, obtiene un acceso token, inicia una tarea de Task Guard, comprueba una acción material, corre Secure y Govern, registra el resultado y completa la tarea.

Reemplazamiento https://mcp.maetra.io con tu desplegable MCP host.

1. Inicializar#

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

La respuesta incluye instrucciones de servidor para las capacidades habilitadas en el espacio de trabajo.

2. Herramientas de Discover#

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

El resultado siempre incluye get_mcp_access, entonces incluye sólo las herramientas de Task Guard, Secure y Govern permitidas para el espacio de trabajo actual y la clave.

3. Obtener acceso a la capacidad#

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

Leer structuredContent.mcp_access_token, expires_at, y las capacidades habilitadas. Los ejemplos que se indican a continuación utilizan <ACCESS_TOKEN> por ese valor de vida corta.

Call get_mcp_access una vez más al comienzo de cada nuevo giro del usuario o ciclo de trabajo.

4. Comiencen la tarea de Task Guard#

Si Task Guard está habilitada:

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

Retener el ancla y el anclaje de tareas devueltos contract_version.

5. Ajuste de la tarea de verificación#

Antes de la acción material:

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

Procede sólo para ALIGNED o SUPPORTING. Explicación NEEDS_EXPLANATION, pregunte la línea de usuario para USER_CONFIRMATION_REQUIRED, contexto refrescante para CONTEXT_REFRESH_REQUIRED, y replan o paran para REFOCUS o STOPPED.

6. Corre Secure#

Si Secure está habilitada, escanee la llamada de la herramienta antes de la ejecución:

{
  "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\"}"
    }
  }
}

No proceda cuando Secure regrese bloqueado. Examen flagged según tu flujo de trabajo.

7. Solicitar la aprobación de Govern#

Si Govern está habilitada:

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

Si el resultado es pendientes, votación:

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

Sigue encuestando hasta la terminal. Parar a menos que el resultado sea aprobado. La aprobación no es la llamada del proveedor: el siguiente paso consume esa aprobación para una ejecución exacta.

8. Autorizar la ejecución exacta#

Inmediatamente antes de llamar al proveedor de facturación:

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

Retened el devuelto executionId. Sólo ahora envía esa solicitud exacta al proveedor. Repetir esta autorización con la misma solicitud clave e idéntica devuelve la recepción existente; cambiar los conflictos de solicitud.

9. Grabar el intento del proveedor#

Después de que el proveedor responda:

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

Para un tiempo de salida o fracaso, use failed o unknown. Un proveedor idéntico se mantiene bajo el mismo ID de ejecución y utiliza el número de intento 2.

10. Grabar el efecto de ejecución observado#

Lea el proveedor resultante o estado del libro mayor, después adjuntelo a la misma ejecución:

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

Este ejemplo utiliza self_reported, por lo que el recibo permanece explícitamente unverified. Uso provider_signed, ledger_readback, u otro método independiente sólo cuando se configura el verificador de prueba correspondiente.

11. Informe el efecto a Task Guard#

Cuando Task Guard reporte de efectos está habilitado:

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

Si. effect_aligned es falso, pregunte la línea de usuario de la sesión antes de ampliar más.

12. Completar la tarea#

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

Usted puede conseguir solicitudes independientes de JSON-RPC tales como initialize y tools/list. No lo hagas. get_mcp_access con llamadas de capacidad que necesitan su token devuelto. No entregues secuencialmente Task Guard, Secure, Govern, ejecución y pasos de reportaje de efectos cuyos insumos o permiso dependen del resultado anterior.