MCP tools

Fluveo MCP lists the tools below, and an agent reaches the API operations further down through them. A tool call sends the tool's name and an arguments object that matches its input. Fluveo MCP shows how to add the server to a client, and Authentication covers agent keys.

Tools#

The server lists its tools by name, in this order. A key sees only the tools its permissions allow, so a key without Read on Account gets no get_account_info in its list.

cancel_payment#

Cancels a payment that is not paid or captured yet, such as one in requires_capture, and releases the amount held on the buyer's card. It writes. Its operation needs approval for an agent key: a person approves each cancellation in the Dashboard, within 15 minutes.

{
  "name": "cancel_payment",
  "arguments": {
    "payment_intent": "pi_...",
    "cancellation_reason": "requested_by_customer"
  }
}

It answers like fluveo_api_write. The first call cancels nothing: the answer gives approval with status required, the approval_request id, the approval_url of the Dashboard and expires_at, then human_confirmation and an instruction. Once a person approves, call cancel_payment again with the same arguments and that human_confirmation: it answers the operation_id post-v1-payment-intents-intent-cancel, the API's HTTP status and request_id, and the PaymentIntent, now canceled, inside untrusted_data. When the person denies it, nothing is cancelled.

capture_payment#

Takes the amount a payment holds on the buyer's card, so the store is paid: all of it, or amount_to_capture, and the rest of the hold is released. It works on a PaymentIntent in requires_capture, one made with capture_method manual. It writes. Its operation needs approval for an agent key: a person approves each capture in the Dashboard, within 15 minutes.

{
  "name": "capture_payment",
  "arguments": {
    "payment_intent": "pi_...",
    "amount_to_capture": 2000
  }
}

It answers like fluveo_api_write. The first call captures nothing: the answer gives approval with status required, the approval_request id, the approval_url of the Dashboard and expires_at, then human_confirmation and an instruction. Once a person approves, call capture_payment again with the same arguments and that human_confirmation: it answers the operation_id post-v1-payment-intents-intent-capture, the API's HTTP status and request_id, and the PaymentIntent, now succeeded, inside untrusted_data. A further retry answers the same capture, never a second one. When the person denies it, nothing is captured and the payment stays in requires_capture.

create_checkout_session#

Creates a Fluveo payment page for one purchase. The buyer opens the session's url and pays there with a method the store accepts, and types any card data on that page, never in the call. It writes. Its operation is allowed for an agent key, so it runs at once, with no approval.

{
  "name": "create_checkout_session",
  "arguments": {
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "usd",
          "unit_amount": 2500,
          "product_data": {
            "name": "T-shirt"
          }
        }
      }
    ],
    "success_url": "https://shop.example.com/thanks?session={CHECKOUT_SESSION_ID}"
  }
}

It answers like fluveo_api_write: the operation_id post-v1-checkout-sessions, the API's HTTP status and request_id, and the session, cs_test_..., inside untrusted_data, with its url, the page to send the buyer to. The server sends the request with an Idempotency-Key it draws for the call. When the API gives no usable answer, the tool error api_unavailable gives a human_confirmation: call create_checkout_session again with the same arguments and that human_confirmation, and the same request is sent again, never a second one.

create_customer#

Creates a customer of the store, to keep a buyer's contact details and link their payments, checkout sessions and refunds. It writes. Its operation is allowed for an agent key, so it runs at once, with no approval.

{
  "name": "create_customer",
  "arguments": {
    "name": "Jenny Rosen",
    "email": "jenny@example.com",
    "metadata": {
      "order": "1234"
    }
  }
}

It answers like fluveo_api_write: the operation_id post-v1-customers, the API's HTTP status and request_id, and the new customer, cus_..., inside untrusted_data, with secrets withheld. The server sends the request with an Idempotency-Key it draws for the call. When the API gives no usable answer, the tool error api_unavailable gives a human_confirmation: call create_customer again with the same arguments and that human_confirmation, and the same request is sent again, never a second one.

create_payment_link#

Creates a link anyone can open to pay for the same items on a Fluveo payment page, as many times as the link stays active. It writes. Its operation is allowed for an agent key, so it runs at once, with no approval.

{
  "name": "create_payment_link",
  "arguments": {
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "usd",
          "unit_amount": 2500,
          "product_data": {
            "name": "T-shirt"
          }
        }
      }
    ]
  }
}

It answers like fluveo_api_write: the operation_id post-v1-payment-links, the API's HTTP status and request_id, and the link, plink_..., inside untrusted_data, with its url to share. The server sends the request with an Idempotency-Key it draws for the call. When the API gives no usable answer, the tool error api_unavailable gives a human_confirmation: call create_payment_link again with the same arguments and that human_confirmation, and the same request is sent again, never a second one.

create_refund#

Gives the buyer back all or part of a payment that succeeded, by its PaymentIntent or its charge. It writes and moves money, so a person approves each refund in the Dashboard before it runs, within 15 minutes. Before it asks for that approval, it reads the payment's charges with the agent's key. When that read answers, it refuses at once, with no refund sent and no approval made, if the payment has nothing captured, if the amount is above what is left to refund, or if no amount is given and nothing is left. A read that fails, or that the key may not make, refuses nothing. That read only helps the agent: the API decides every refund. A Boleto payment cannot be refunded, and the API answers an error.

{
  "name": "create_refund",
  "arguments": {
    "payment_intent": "pi_...",
    "amount": 400,
    "reason": "requested_by_customer"
  }
}

The first call runs nothing: it answers approval with status required, the approval_request id, the approval_url of the Dashboard and expires_at, then human_confirmation and an instruction. Show the URL to the person, and once they approve it, call create_refund again with the same arguments and that human_confirmation. That call answers like fluveo_api_write: the operation_id post-v1-refunds, the API's HTTP status and request_id, and the refund, re_..., inside untrusted_data. The same call again answers the same refund, never a second one. When the refund cannot fit, the tool error refund_exceeds_refundable says in its message that nothing was captured, or what is left to refund, names in param the amount or the payment's argument when one of them is at fault, and has no status, since no refund request reached the API.

fetch_fluveo_doc#

Returns one page of these docs as Markdown, by its path or by its address on the docs site.

{
  "name": "fetch_fluveo_doc",
  "arguments": {
    "path": "/payments/pix"
  }
}

It answers the page's url and title, its Markdown in content, and truncated, which is true when the page passed 60 KB and was cut there.

fluveo_api_details#

Describes one API operation by the id that fluveo_api_search returned. It reads the server's own copy of the API contract and calls no API.

{
  "name": "fluveo_api_details",
  "arguments": {
    "operation_id": "get-v1-customers"
  }
}

It answers the operation's method, path, summary, description, its path, query and body parameters, the response_object, access, permission, policy, window, llm_context, available and the errors_url of the errors page.

fluveo_api_read#

Runs one GET operation of the API with the agent's own key and returns the store's data. It runs only a GET operation whose available is true.

{
  "name": "fluveo_api_read",
  "arguments": {
    "operation_id": "get-v1-customers-customer",
    "parameters": {
      "customer": "cus_..."
    }
  }
}

It answers the operation_id, the API's HTTP status and request_id, limit_capped, and the API's answer inside untrusted_data, with secrets withheld and, in a list, customer names, emails, phones, addresses and tax ids masked. When the key lacks the operation's permission, the tool error carries the API's 403, whose message names the permission.

fluveo_api_search#

Finds API operations from what the agent wants to do and the resource it acts on. It reads the server's own copy of the API contract and calls no API.

{
  "name": "fluveo_api_search",
  "arguments": {
    "intent": "list",
    "resource": "refund",
    "limit": 5
  }
}

It answers the api_version and, in data, the best operations, each with its id, method, path, summary, path_params, access, permission, policy, llm_context and available.

fluveo_api_write#

Runs one POST or DELETE operation of the API with the agent's own key, such as creating a customer or a refund. It runs only an operation whose available is true. An operation that needs approval runs only after a person approves it in the Dashboard.

{
  "name": "fluveo_api_write",
  "arguments": {
    "operation_id": "post-v1-refunds",
    "parameters": {
      "payment_intent": "pi_...",
      "amount": 500
    }
  }
}

It answers the operation_id, the API's HTTP status and request_id, and the API's answer inside untrusted_data, with secrets withheld. When the operation needs a person, nothing runs: the answer gives approval with status required, the approval_request id, the approval_url of the Dashboard and expires_at, then human_confirmation and an instruction. Agent approvals shows the retry. When the API gives no usable answer, the tool error api_unavailable gives a human_confirmation that sends the same request again, never a second one. When the key lacks the operation's permission, the tool error carries the API's 403.

get_account_info#

Returns the store behind the key and what the key may do on each resource. Call it first, to know which store the agent acts on.

It takes no arguments. Send an empty arguments object.

{
  "name": "get_account_info",
  "arguments": {}
}

It answers the store's account_id, livemode (always false), country, default_currency, charges_enabled, payouts_enabled, the key's permissions, the dashboard_api_keys_link and a request_id, with the store's display name inside untrusted_data.

get_balance#

Returns the store's balance in test mode: what is available to pay out and what is still pending, per currency. It only reads.

It takes no arguments. Send an empty arguments object.

{
  "name": "get_balance",
  "arguments": {}
}

It answers like fluveo_api_read: the operation_id get-v1-balance, the API's HTTP status and request_id, and the API's balance object inside untrusted_data.

list_customers#

Lists the store's customers, newest first, at most 25 per call. It only reads.

{
  "name": "list_customers",
  "arguments": {
    "email": "jenny@example.com",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-customers, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page. Each customer's name, email, phone, address, shipping and tax ids are masked in the list, and retrieve_customer shows them. Metadata and descriptions are not masked: they arrive as the store's data, inside untrusted_data.

list_disputes#

Lists the store's disputes, newest first, at most 25 per call. A dispute is a buyer contesting a payment with their bank. It only reads.

{
  "name": "list_disputes",
  "arguments": {
    "payment_intent": "pi_...",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-disputes, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page. Evidence and buyer text arrive as the store's data, inside untrusted_data.

list_events#

Lists what happened on the store in the last 30 days, newest first, at most 25 per call. Each event names its type, such as charge.succeeded, and carries the object as it was then. It only reads.

{
  "name": "list_events",
  "arguments": {
    "type": "charge.*",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-events, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page.

list_payments#

Lists the store's payments, newest first, at most 25 per call. Each is a PaymentIntent, one per payment a buyer makes or tries, with its amount, currency, status and payment method. It only reads.

{
  "name": "list_payments",
  "arguments": {
    "customer": "cus_...",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-payment-intents, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page.

list_refunds#

Lists the store's refunds, newest first, at most 25 per call, each with its amount, currency, status and the payment it belongs to. It only reads.

{
  "name": "list_refunds",
  "arguments": {
    "payment_intent": "pi_...",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-refunds, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page.

list_webhook_endpoints#

Lists the URLs the store sends its events to, with the event types each receives and whether it is enabled, at most 25 per call. It only reads.

{
  "name": "list_webhook_endpoints",
  "arguments": {
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-webhook-endpoints, the API's HTTP status and request_id, limit_capped, and the API's list inside untrusted_data, with has_more for the next page. Signing secrets are withheld. The Dashboard shows them.

retrieve_customer#

Returns one customer by its id, with its name, email, phone, address and metadata. It only reads.

{
  "name": "retrieve_customer",
  "arguments": {
    "customer": "cus_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-customers-customer, the API's HTTP status and request_id, and the customer inside untrusted_data, unmasked.

retrieve_dispute#

Returns one dispute by its id: its amount, reason and status, the charge it contests, the deadline for evidence and the evidence sent so far. It only reads.

{
  "name": "retrieve_dispute",
  "arguments": {
    "dispute": "du_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-disputes-dispute, the API's HTTP status and request_id, and the dispute inside untrusted_data. Evidence and buyer text arrive as the store's data, inside untrusted_data.

retrieve_event#

Returns one event by its id: its type, when it happened, and the object as it was then, with the fields that changed in previous_attributes. It only reads.

{
  "name": "retrieve_event",
  "arguments": {
    "event": "evt_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-events-id, the API's HTTP status and request_id, and the event inside untrusted_data.

retrieve_payment#

Returns one payment by its PaymentIntent id: its amount, the amount still held and the amount received, its currency, status, customer, payment method, latest charge and metadata. It only reads.

{
  "name": "retrieve_payment",
  "arguments": {
    "payment_intent": "pi_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-payment-intents-intent, the API's HTTP status and request_id, and the PaymentIntent inside untrusted_data.

retrieve_refund#

Returns one refund by its id: its amount, currency, status, reason and the payment it belongs to. It only reads.

{
  "name": "retrieve_refund",
  "arguments": {
    "refund": "re_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-refunds-refund, the API's HTTP status and request_id, and the refund inside untrusted_data.

retrieve_webhook_endpoint#

Returns one webhook endpoint by its id: its URL, the event types it receives and whether it is enabled. It only reads.

{
  "name": "retrieve_webhook_endpoint",
  "arguments": {
    "webhook_endpoint": "we_..."
  }
}

It answers like fluveo_api_read: the operation_id get-v1-webhook-endpoints-webhook-endpoint, the API's HTTP status and request_id, and the endpoint inside untrusted_data. Its signing secret is withheld. The Dashboard shows it.

search_fluveo_docs#

Finds the pages of these docs, guides and API reference both, that best answer a question.

{
  "name": "search_fluveo_docs",
  "arguments": {
    "question": "refund a Pix payment"
  }
}

It answers the best pages in results, each with its title, url, section, description and the passage that matches best in content.

search_payments#

Finds the store's payments that match a query, newest first, at most 25 per call. A query joins clauses of field:'value' with AND, or with OR, never both. The fields are status, amount, currency, customer, created and metadata['key'], and amount and created also take >, >=, < and <=. It only reads.

{
  "name": "search_payments",
  "arguments": {
    "query": "status:'requires_capture' AND currency:'brl'",
    "limit": 10
  }
}

It answers like fluveo_api_read: the operation_id get-v1-payment-intents-search, the API's HTTP status and request_id, limit_capped, and the matching payments inside untrusted_data, with has_more and next_page for the next page.

update_customer#

Changes the fields given of one customer and keeps the rest. It writes. Its operation is allowed for an agent key, so it runs at once, with no approval.

{
  "name": "update_customer",
  "arguments": {
    "customer": "cus_...",
    "phone": "+15555550123"
  }
}

It answers like fluveo_api_write: the operation_id post-v1-customers-customer, the API's HTTP status and request_id, and the customer as it is now inside untrusted_data, with secrets withheld. When the API gives no usable answer, the tool error api_unavailable gives a human_confirmation: call update_customer again with the same arguments and that human_confirmation, and the same request is sent again.

Operations#

Every operation of the API, with the permission a restricted key needs to call it and the policy for an agent key. The API applies that policy to each call an agent key makes. An allowed operation runs at once. An operation that needs approval runs only after a person approves that one request in the Dashboard, and the approval expires after the time the table gives. A denied operation always answers 403. Through this server, fluveo_api_read runs the allowed GET operations. fluveo_api_write runs the allowed POST and DELETE operations, and those that need approval once a person approves the request. It refuses a denied operation before the request reaches the API. fluveo_api_search and fluveo_api_details list every operation, each with available set to false when this server does not run it. Approvals covers what a person sees and approves.