Agents

MCP agent integration

Lipafy exposes an MCP server at:

POST https://api.lipafy.xyz/mcp

The endpoint uses JSON-RPC over HTTP. It supports initialize, ping, tools/list, and tools/call.

Authentication

MCP clients should use OAuth when they support it. Lipafy publishes:

https://api.lipafy.xyz/.well-known/oauth-protected-resource/mcp
https://api.lipafy.xyz/.well-known/oauth-authorization-server

The OAuth server supports authorization code + PKCE, refresh tokens, dynamic client registration, and token revocation.

If the user is not signed in when the OAuth flow starts, Lipafy sends them to the dashboard login page and then returns them to the original OAuth authorization request after login.

Current OAuth scopes:

ScopeMeaning
lipafy.gatewayCall paid capabilities through Lipafy
lipafy.wallet.readRead wallet and usage information

Client setup

Use this server config in clients that support Streamable HTTP MCP:

1{
2  "mcpServers": {
3    "lipafy": {
4      "type": "http",
5      "url": "https://api.lipafy.xyz/mcp"
6    }
7  }
8}

Client behavior differs. Some hosts start the OAuth flow from the MCP metadata; others require you to paste a bearer token or run their own connect/login command.

Tools

Lipafy currently exposes these built-in MCP tools. Active capabilities can also appear as direct dynamic tools when their slugs do not conflict with built-in tool names.

Read tools

ToolWhat it returns
lipafy.whoamiThe connected account, its @lipafy tag, and whether it can send/receive money
lipafy.list_capabilitiesActive capabilities the connected account can call
lipafy.list_containersCapability containers
lipafy.get_containerOne container and its capabilities
lipafy.get_balanceWallet balance, held amount, and available amount
lipafy.get_usageSpend summary for a date range
lipafy.list_transfersRecent money transfers sent and received
lipafy.get_transferOne transfer receipt
lipafy.list_trusted_recipientsPeople the account may pay hands-off, and their limits
lipafy.list_intentsScheduled time-based intents
lipafy.list_intent_mandatesSigned condition-based mandates
lipafy.get_intent_mandateOne mandate’s budget, conditions, and status

Capability + wallet action tools

ToolWhat it does
lipafy.initiate_topupStarts a wallet top-up through the configured payment rail
lipafy.execute_capabilityCalls a paid capability through the gateway
lipafy.schedule_capabilitySchedules a capability call for a future time
lipafy.cancel_intentCancels a pending scheduled intent
lipafy.request_approvalCreates an approval request when a payment needs human review
lipafy.fulfill_intent_mandateExecutes against an existing signed mandate

Send money to a person

ToolWhat it does
lipafy.send_moneySend to a person in the fewest steps — auto-sends to a trusted recipient within limits, otherwise previews for confirmation
lipafy.resolve_recipientLook up a recipient by @tag, phone, or name before paying
lipafy.quote_transferQuote an exact debit before sending
lipafy.confirm_transferSettle a quoted transfer (with approval when required)
lipafy.add_trusted_recipientPre-authorize a recipient with limits so future payments are hands-off

Approval behavior

Lipafy is not meant to ask the user before every ordinary payment. The intended flow is:

  1. The user connects the agent once.
  2. Lipafy checks the grant, wallet balance, spending controls, capability rules, and mandate rules on each action.
  3. If the action is allowed, execution continues.
  4. If the action needs a top-up, exceeds controls, or needs human review, the tool response tells the agent to pause and request approval.

For most in-policy calls, agents should use lipafy.execute_capability directly. Use lipafy.request_approval only when Lipafy returns escalation_required or the agent is about to do something high-value or risky.

Example

Call demo.echo with {"foo":"bar"}.

The agent should:

  1. Call lipafy.list_capabilities if it does not know the slug.
  2. Call lipafy.execute_capability with the slug and request body.
  3. If Lipafy returns an approval or top-up requirement, stop and surface that to the user.

Current support

  • MCP responses use JSON over HTTP.
  • OAuth supports gateway access and wallet read access.
  • Capability-level execution is controlled by wallet balance, grants, spending controls, approvals, and mandates.