MCP tool reference
The 13 tools that the Appmax MCP server exposes to AI agents. Each entry shows: what you ask, what the agent calls under the hood, and what it returns.
Prerequisite
To use these tools, your agent must be connected to the MCP server. See the configuration.
Documentation
search_docs · semantic search
You ask: "How does the payment confirmation webhook work?"
The agent calls: search_docs({ "query": "webhook payment confirmation" })
Returns: relevant excerpts from the webhooks and order status guides. The agent answers grounded in real content — no hallucinated endpoints or fields.
list_pages · enumerate what exists
You ask: "What payment methods does Appmax support?"
The agent calls: list_pages({ "prefix": "api-" })
Returns: all 15 API Reference pages — including api-apple-pay, api-pix, api-boleto, api-cartao-de-credito, api-tokenizacao, api-parcelas. Deterministic, no search ranking dependency.
get_page · full guide content
You ask: "I need to implement card tokenization from scratch."
The agent calls: get_page({ "page": "api-tokenizacao" })
Returns: the complete guide in markdown — endpoints, required fields, examples and edge cases.
get_full_docs · entire documentation
You ask: "Load all of the Appmax documentation into context."
The agent calls: get_full_docs({ "lang": "en" })
Returns: ~140 KB of plain text with every page. Use sparingly — prefer search_docs + get_page for targeted lookups.
check_health · server status
The agent calls: check_health({})
Returns: server status, version, available tools, and stats (page count by language, corpus size).
Diagnostics
diagnose_error · HTTP error root cause
You ask: "I'm getting 401 on /v1/customers, what is it?"
The agent calls: diagnose_error({ "status_code": 401, "endpoint": "/v1/customers", "credential_type": "app" })
Returns: "You're using app credentials on a merchant endpoint. Use the merchant token." — with a link to the authentication guide.
Scenarios covered: 401 (swapped credentials, expired token), 403 (wrong URL), 404 (resource not found), 422 (incomplete flow, invalid payload), 429 (rate limit), 500 (health check failed), 502 (webhook failed), 503 (service unavailable).
validate_payload · validate payload before sending
You ask: "Validate this JSON before I send it to the create order API"
The agent calls: validate_payload({ "endpoint": "create_order", "payload": "{...}" })
Returns: list of issues — float instead of cents, products_value and unit_value used together, missing required fields. Prevents the 422 before calling the API.
Supported endpoints: create_customer, create_order, pay_credit_card, pay_pix, pay_boleto, pay_apple_pay, tokenize, refund, create_recurrence.
validate_order_total · verify order calculation
You ask: "The order total should be R$214.80 but the API rejects it"
The agent calls: validate_order_total({ "products": [...], "shipping_value": 1500, "expected_total": 21480 })
Returns: detailed breakdown (subtotal + shipping - discount = total), comparison with the provided value, and detection of common errors (float, mutual exclusion, rounding).
validate_installation_flow · audit the installation flow implementation
You ask: "Review whether my installation flow is correct"
The agent calls: validate_installation_flow({ "snippets": [{ "step": "app_token", "code": "..." }, { "step": "authorize", "code": "..." }, { "step": "validation_url", "code": "..." }], "environment": "sandbox" })
Returns: a per-step report with status (OK, Issues, Missing), evidence for each check (correct base URL for the environment, HTTP method, headers, payload, external_id format, etc.) and a list of next steps. It detects the most frequent mistakes: app_id sent as the Numerical ID instead of the UUID, missing url_callback, a validation URL handler that only accepts GET, a response shaped as {"status":"ok"} instead of {"external_id":"<UUID>"}, a hardcoded external_id, and merchant credentials used in place of the app ones.
Supported steps: app_token (POST /oauth2/token with the APP credentials), authorize (POST /app/authorize), redirect (browser redirect to the Appmax panel), generate (POST /app/client/generate), validation_url (the handler the integrator exposes for the health check).
Code generation
generate_code_snippet · snippets in 5 languages
You ask: "Give me the Python code to create a Pix payment in sandbox"
The agent calls: generate_code_snippet({ "endpoint": "pay_pix", "language": "python", "environment": "sandbox" })
Returns: ready-to-use code with the correct URL, headers, body, and notes — in curl, Node.js, Python, PHP, or Go.
Supported endpoints: auth, auth_app, create_customer, create_order, get_order, upsell, pay_credit_card, pay_pix, pay_boleto, pay_apple_pay, tokenize, installments, refund, create_recurrence, app_authorize, app_generate.
get_integration_flow · step-by-step flow
You ask: "What's the endpoint sequence to install my app?"
The agent calls: get_integration_flow({ "flow": "app_installation", "environment": "sandbox" })
Returns: wizard with the 4 steps (token → authorize → redirect → generate), environment-specific URLs, per-step prerequisites, and health check notes.
Available flows: app_installation, checkout_credit_card, checkout_pix, checkout_boleto, subscription, refund, upsell.
Onboarding and webhooks
get_onboarding_checklist · admin checklist
You ask: "I'm starting from scratch, what do I need to do to integrate?"
The agent calls: get_onboarding_checklist({ "integration_type": "checkout_proprio", "stage": "planning" })
Returns: personalized checklist — create account, create app, configure URLs, get credentials, implement flow, test, publish. Each item links to the relevant guide.
Integration types: checkout_proprio, plataforma_publica, recorrencia, upsell.
Stages: planning, development, sandbox_testing, production_ready.
get_webhook_schema · typed event schemas
You ask: "I need the TypeScript types for the order approved webhook"
The agent calls: get_webhook_schema({ "event": "order_approved" })
Returns: complete schema with all typed fields (order_id: int, total: int, payment_info.credit_card.installments: int, etc.) + example JSON payload. The agent generates TS/Go/Python types from this.
Event types: order (18 events), customer (3), payment (2), subscription (5). Call with no parameters to see the full list.
Native multi-language
All documentation tools accept a lang parameter (pt or en). Your team works in the documentation's native language, with no translation step in between.