Procurement for agents

This page is the operational guide for an agent procuring Safeguard on behalf of its user. It complements the MCP payments & procurement reference with the recommended conversation flow.

Prerequisites

• The billing tools are opt-in — an administrator must enable them for the workspace (mcp:tool:safeguard_list_pricing_plans, mcp:tool:safeguard_purchase_plan, mcp:tool:safeguard_list_billing_invoices, mcp:tool:safeguard_get_subscription_entitlements) in the admin console; only the 10 core tools are on by default (see tool gating).
• The session is authenticated into the tenant that will be buying. Purchases are pinned to the session tenant — there is no way (by design) to buy for another tenant. No account yet? Start at Step 0.

Step 0 — No account yet? Create one

Brand-new users don't need a browser or a human signup. (Lost password later? safeguard_request_password_reset → safeguard_reset_password.) Connect to the pre-auth endpoint mcp.safeguard.sh/mcp/onboarding (the regular /mcp endpoint requires OAuth) — it exposes the account-onboarding tools:

// safeguard_create_account
{
  "email": "founder@newco.io",
  "password": "<strong password>",
  "first_name": "Ada",
  "last_name": "Lovelace"
}

• A workspace (tenant) is provisioned for the email's domain — or joined, if colleagues already created one.
• If the platform doesn't require email verification, the tool signs this session in immediately — skip to Step 1.
• If verification is required, get the token from the verification email (agents with inbox access can do this themselves), call safeguard_verify_email with it, then safeguard_login with the email and password. safeguard_login authenticates THIS session in place — every subsequent call runs as the new account. (safeguard_resend_verification if the email went missing.)
• Accounts with 2FA enabled pass totp_code to safeguard_login.

Passwords are never echoed back or logged; the session holds only the resulting access token, server-side.

Step 1 — Resolve the user's pricing region

Send everything you know about where the user is. You do not need a clean country code — the server analyses all signals offline and explains its choice:

// safeguard_list_pricing_plans
{
  "location": {
    "country_name": "India",
    "locale": "en-IN",
    "timezone": "Asia/Kolkata",
    "city": "Bengaluru",
    "district_or_state": "Karnataka",
    "currency": "INR"
  },
  "audience": "TEAM"
}

Signal precedence: explicit ISO country → country_name → locale region → timezone → unambiguous currency. A continent, city, or IP address alone cannot safely select one country and falls back to GLOBAL pricing — the response's Pricing region section tells you exactly what happened, so you can ask the user for a stronger signal if it matters.

Step 2 — Compare tiers and audiences

The response groups plans by product. For each plan you get:

• Tier (PRO, MAX, 5X, 20X, ENTERPRISE …) — depth: quotas and the feature set enabled on activation
• Audience (INDIVIDUAL single user · TEAM · ENTERPRISE · SHARED for everyone) — fit; filter with audience, SHARED plans always included
• Monthly and yearly prices (yearly defaults to 20% off when no explicit yearly price exists)
• The feature list that tier unlocks
• Whether it is purchasable online, or needs a sales contact

Recommend by matching the user's stated need (a quota to lift, a feature to unlock, a team size) against tier features and price — and say why.

Step 3 — Purchase (fully automatic when a card is on file)

Check safeguard_get_payment_method_status first:

• Card on file → safeguard_purchase_plan_autopay charges it immediately and activates the plan on the spot — no checkout page, no human. Done; skip to Step 4.
• No card yet → the first purchase goes through Stripe Checkout (below), which saves the card so every future purchase can use autopay. Manage what's active with safeguard_list_subscriptions / safeguard_cancel_subscription.

First purchase — Stripe Checkout

// safeguard_purchase_plan
{
  "plan_id": 42,
  "interval": "year",
  "email": "buyer@example.com"
}

The tool returns a Stripe-hosted checkout URL. Hand that link to the user — payment is completed on Stripe's page, never in the conversation. Do not ask for, accept, or relay card details; if the user pastes them, tell them to use the link instead. Workspaces with a saved payment method check out in one click.

Step 4 — Verify the purchase

After the user reports paying (or on their next message), confirm rather than assume:

1. safeguard_list_billing_invoices — the new invoice should show status paid. That is the procurement receipt; it includes a PDF link for records.
2. safeguard_get_subscription_entitlements — lists the feature flags now enabled, so you can tell the user exactly what their new tier switched on.

Activation is automatic on payment (usage limits raised, product license granted). If the user's scans were paused on a usage limit, they can now be resumed. Billing and activation events also land in the user's notification inbox — check them with safeguard_list_notifications / safeguard_get_notification.

Failure modes

Audit expectations

Every call you make on this journey — including read-only pricing and invoice pulls — is recorded with your tenant, user, action, and outcome, and the money events (activation, license grant) land in the platform audit log. Behave as if the compliance team is watching, because they can.