{"openapi":"3.1.0","info":{"title":"Mercado Pago (BYOK) API","version":"0.1.0","description":"Mercado Pago (BYOK) lets an AI assistant read your own Mercado Pago data through the Mercado Pago API with a key you supply (access token (APP_USR-...)). Read-only: 9 tools (search_payments, get_payment, search_customers, search_orders, get_order, search_merchant_orders, search_subscriptions, search_subscription_plans, list_payment_methods). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mercadopago.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mercadopago/docs"},"termsOfService":"https://connectorbay.com/byok-mercadopago/terms"},"servers":[{"url":"https://byok-mercadopago.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mercadopago/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_payments":{"post":{"operationId":"search_payments","summary":"Search payments of the last twelve months with status, amount, currency, payment method, fees received and dates; filter","description":"Search payments of the last twelve months with status, amount, currency, payment method, fees received and dates; filter by reference, date range, store or POS. Use for \"Which Mercado Pago payments were approved in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["date_approved","date_created","date_last_updated","id","money_release_date"],"type":"string"},{"type":"null"}],"default":"date_created","description":"Order by: date_approved, date_created, date_last_updated, id or money_release_date.","title":"Sort"},"criteria":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc.","title":"Criteria"},"range":{"anyOf":[{"enum":["date_created","date_last_updated","date_approved","money_release_date"],"type":"string"},{"type":"null"}],"default":"date_created","description":"Which date the begin and end dates refer to: date_created, date_last_updated, date_approved or money_release_date.","title":"Range"},"begin_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the interval: a relative date such as NOW-30DAYS or an ISO 8601 date such as 2026-01-01.","title":"Begin Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the interval: NOW, a relative date or an ISO 8601 date.","title":"End Date"},"external_reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference of the payment.","title":"External Reference"},"store_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments of this store id.","title":"Store Id"},"pos_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments of this point-of-sale id.","title":"Pos Id"},"collector_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments received by this collector id.","title":"Collector Id"},"payer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments made by this payer id.","title":"Payer Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"title":"search_paymentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_payment":{"post":{"operationId":"get_payment","summary":"Get one payment by id: status, amount, currency, payment method, net amount received and dates; card and payer identity ","description":"Get one payment by id: status, amount, currency, payment method, net amount received and dates; card and payer identity details are left out. Use for \"What is the status of Mercado Pago payment 1234567890\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Payment id (a number).","title":"Id","type":"integer"}},"required":["id"],"title":"get_paymentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_customers":{"post":{"operationId":"search_customers","summary":"Find customers by email, with name, creation dates and live-mode flag; documents, phones, addresses and cards are left o","description":"Find customers by email, with name, creation dates and live-mode flag; documents, phones, addresses and cards are left out. Use for \"Is there a Mercado Pago customer with the email ana@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"description":"Customer email to look up.","maxLength":200,"title":"Email","type":"string"}},"required":["email"],"title":"search_customersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_orders":{"post":{"operationId":"search_orders","summary":"Search orders (Orders API) by creation date range, with type, status, total and paid amounts; both dates are required. U","description":"Search orders (Orders API) by creation date range, with type, status, total and paid amounts; both dates are required. Use for \"Which Mercado Pago orders were processed this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"begin_date":{"description":"Start of the creation interval, RFC 3339, for example 2026-01-01T00:00:00Z.","maxLength":200,"title":"Begin Date","type":"string"},"end_date":{"description":"End of the creation interval, RFC 3339.","maxLength":200,"title":"End Date","type":"string"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Order status to filter by.","title":"Status"},"status_detail":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Status detail to filter by.","title":"Status Detail"},"external_reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference of the order.","title":"External Reference"},"payment_method_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Payment method id to filter by.","title":"Payment Method Id"},"payment_method_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Payment method type to filter by.","title":"Payment Method Type"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc by creation date.","title":"Sort Order"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many orders per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["begin_date","end_date"],"title":"search_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one order (Orders API) by id: type, status, total and paid amounts and dates. Use for \"Show Mercado Pago order ORD01","description":"Get one order (Orders API) by id: type, status, total and paid amounts and dates. Use for \"Show Mercado Pago order ORD01J49MMW3SSBK5PSV3DFR32959\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Order id, for example ORD01J49MMW3SSBK5PSV3DFR32959.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_merchant_orders":{"post":{"operationId":"search_merchant_orders","summary":"Search merchant orders of the last 90 days with status, reference, total, paid and refunded amounts and dates. Use for \"","description":"Search merchant orders of the last 90 days with status, reference, total, paid and refunded amounts and dates. Use for \"Which Mercado Pago merchant orders are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Merchant order status to filter by.","title":"Status"},"preference_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders of this checkout preference id.","title":"Preference Id"},"external_reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference of the order.","title":"External Reference"},"date_created_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created after this date, ISO 8601.","title":"Date Created From"},"date_created_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created before this date, ISO 8601.","title":"Date Created To"},"last_updated_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders updated after this date, ISO 8601.","title":"Last Updated From"},"last_updated_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders updated before this date, ISO 8601.","title":"Last Updated To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"title":"search_merchant_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_subscriptions":{"post":{"operationId":"search_subscriptions","summary":"Search subscriptions (preapprovals) with status, plan, amount, frequency, next payment date and charge summary; filter b","description":"Search subscriptions (preapprovals) with status, plan, amount, frequency, next payment date and charge summary; filter by status, plan or payer. Use for \"Which Mercado Pago subscriptions are authorized\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Subscription status, for example authorized, pending, paused or cancelled.","title":"Status"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free search text.","title":"Q"},"preapproval_plan_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this plan id.","title":"Preapproval Plan Id"},"payer_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only subscriptions of this payer id.","title":"Payer Id"},"payer_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions registered with this email.","title":"Payer Email"},"sort":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Sort as field_name:sort_type, for example date_created:desc.","title":"Sort"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"title":"search_subscriptionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_subscription_plans":{"post":{"operationId":"search_subscription_plans","summary":"Search subscription plans with reason, amount, frequency, repetitions, status and subscriber count. Use for \"Which Merca","description":"Search subscription plans with reason, amount, frequency, repetitions, status and subscriber count. Use for \"Which Mercado Pago subscription plans are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Plan status, for example active or inactive.","title":"Status"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free search text.","title":"Q"},"sort":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by.","title":"Sort"},"criteria":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order of the sort: asc or desc.","title":"Criteria"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"title":"search_subscription_plansArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payment_methods":{"post":{"operationId":"list_payment_methods","summary":"List the payment methods available to the account with type, status, allowed amount range and accreditation time. Use fo","description":"List the payment methods available to the account with type, status, allowed amount range and accreditation time. Use for \"Which payment methods does Mercado Pago support for my account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_payment_methodsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}