# How It Works

This page describes from a system perspective how toani Facilitate components work together and how a complete paid tool invocation flows through all layers.

> For product overview, see [toani Facilitate Overview](/toani-facilitate/overview.md). For engine implementation details, see [toani Facilitate Compliance Engine Technical Architecture](/toani-facilitate/facilitate-engine.md).

***

## Component Overview

<figure><img src="/files/aItK31DLkf602tQMLXTC" alt=""><figcaption></figcaption></figure>

***

## Core Components

### MCP Gateway

The gateway is a Node.js process serving as a trust middleware between the Agent and paid MCP services.

| Dimension                | Description                                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Upstream Transport**   | stdio (toward Agent)                                                                                             |
| **Downstream Transport** | SSE / Streamable HTTP (toward MCP services), with automatic protocol fallback                                    |
| **Exposed Tools**        | `list_gateway_services` (enumerate downstream capabilities), `call_service_tool` (invoke with automatic payment) |
| **Core Responsibility**  | Payment interception, compliance pre-check, Google AP2 verification, two-phase payment                           |

### toani Dashboard

A full-stack Next.js 14 App Router application serving simultaneously as user interface and backend API layer.

| Capability                | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| **User Management**       | SIWE authentication; wallet address is identity           |
| **KYC Integration**       | zkMe Widget zero-knowledge identity verification          |
| **KYT Service**           | Real-time wallet risk scanning plus Redis cache           |
| **Intent Mandate**        | Full lifecycle: create, sign, revoke, renew, edit, delete |
| **Transaction Logs**      | Record and query with multidimensional filtering          |
| **Public Key Management** | Required for Google AP2 merchant signature verification   |

### Downstream MCP Services

Third-party tool providers that return HTTP 402 Payment Required when payment is needed. The 402 response contains an x402 payment challenge (amount, network, payee) and optionally a Cart Mandate for Google AP2 verification.

***

## Complete Data Flow: One Paid Tool Invocation

<figure><img src="/files/sIixSj8guj9D8ryI4ztn" alt=""><figcaption></figcaption></figure>

***

## Two-phase Payment Design

| Phase                           | Trigger                                 | Signer         | Behavior                                                                                      |
| ------------------------------- | --------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| **Automatic Payment (Phase 1)** | Compliance pass + within Mandate limit  | Gateway wallet | Gateway automatically creates Payment Mandate (EIP-3009) and completes on-chain settlement    |
| **Manual Approval (Phase 2)**   | Compliance pass + exceeds Mandate limit | Owner wallet   | Return challenge, user manually signs Payment Mandate in browser, payload returned to Gateway |

The manual approval path ensures transactions exceeding preset boundaries can still complete under human oversight, while preserving Agent autonomy.

***

## Integration Approaches Compared

| Approach                     | Typical Use Case                                              | Description                                                                                     |
| ---------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Cursor IDE Configuration** | Developer daily use via `.cursor/mcp.json`                    | Simplest onboarding; Agent directly uses MCP Gateway                                            |
| **Dashboard Management**     | Payer/payee onboarding, Mandate management, transaction audit | Web interface with wallet connection + SIWE login                                               |
| **API Integration**          | Backend communication between Gateway and Dashboard           | API Key authentication; see [API Reference](/toani-facilitate/getting-started/api-reference.md) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toani.ai/toani-facilitate/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.