Mercado Pago MCP. Manage Pix codes, refunds, and card payments from chat.
Gemini Works with every AI agent you already use
…and any MCP-compatible client
Just plug in your AI agents and start using Vinkius.
Mercado Pago connects your AI agent to Brazil's major payment gateway. It handles everything from generating instant Pix QR codes to processing credit card transactions, managing customer records, and issuing full or partial refunds.
You can process payments and track transactions entirely through natural language commands.
What your AI agents can do
Create card
Saves a customer's card details so they can pay with it later.
Create customer
Registers a new buyer into the payment system.
Create payment
Creates a new charge using card details or tokens for established payment methods.
The agent creates a unique, scannable QR code linked to a specific amount, allowing the customer to pay instantly via their banking app.
You initiate a transaction using card details or tokens, charging major credit cards like Visa and Mastercard.
The agent registers new buyers or retrieves existing customer data needed to process payments.
You trigger a refund for any payment ID, specifying if the refund should be partial or full.
The agent pulls up detailed records of past payments by searching using criteria like email address or transaction status.
Ask AI about this MCP
Supported MCP Clients
Gemini Waiting for input…
Mercado Pago MCP Server: 12 Tools for Payment Ops
These tools let your agent perform all financial actions—from creating payments to searching transaction history—directly through conversation.
019d75d2create card
Saves a customer's card details so they can pay with it later.
019d75d2create customer
Registers a new buyer into the payment system.
019d75d2create payment
Creates a new charge using card details or tokens for established payment methods.
019d75d2create pix payment
Generates the QR code data needed for an instant Pix payment scan.
019d75d2create preference
Creates a secure checkout link that redirects customers to finish their purchase.
019d75d2get customer
Retrieves specific details for an existing customer profile.
019d75d2get identification types
Lists all valid ID types (like CPF or CNPJ) the system accepts for customers.
019d75d2get payment
Fetches detailed information about a single payment using its unique ID number.
019d75d2get preference
Retrieves the current settings and status of a specific checkout link.
019d75d2list payment methods
Shows all payment methods supported across Brazil (e.g., various cards or bank transfers).
019d75d2refund payment
Issues a partial or full refund for an existing payment ID.
019d75d2search payments
Searches and finds multiple payments using flexible filters like email, date range, or status.
Choose How to Get Started
Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.
Build Your Own
Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.
- Import from OpenAPI, Swagger, or YAML specs
- Create Agent Skills with progressive disclosure
- Deploy to edge with MCPFusion framework
- Built in DLP, auth, and compliance on every call
- Real time usage dashboard and cost metering
- Publish to catalog or keep private
Make Your AI Do More
Start with Mercado Pago, then connect any of our 4,700+ other servers whenever your AI needs more. One click, no limits.
- Use this MCP plus 4,700+ others, all in one place
- Add new capabilities to your AI anytime you want
- Every connection is secured and compliant automatically
- Track usage and costs across all your servers
- Works with Claude, ChatGPT, Cursor, and more
- New servers added to the catalog every week
What you can do with this MCP connector
This server connects your AI client straight into Mercado Pago. It gives your agent full control over Brazil's major payment gateway functionality, letting you handle everything—from generating instant QR codes to processing card charges and figuring out refunds. You don't need a separate payments platform; your agent does the work.
Managing Buyers & Profiles
When you interact with a customer, your agent first registers them using create_customer if they're new. If you already have their details, you use get_customer to pull up their profile information. To make things easier later, you can also save a buyer's card specifics right away with create_card, so you don't gotta ask for the numbers again.
Processing Payments (The Money Moves)
You have three ways to take money from people. First, for instant payments, your agent generates the necessary QR code data using create_pix_payment. This lets the customer pay immediately through their bank app by scanning it. Second, you process traditional card charges; you initiate a transaction with create_payment using either card details or saved tokens, charging major cards like Visa and Mastercard.
Third, if you're setting up an online store checkout, your agent creates a secure payment link using create_preference. This link redirects the buyer to finish their purchase, and you can check its status anytime with get_preference.
Getting Info on Methods and Payments
Before charging anyone, you can see what methods are available across Brazil by calling list_payment_methods. To understand a specific transaction, you use get_payment with the unique ID to pull up detailed records. If you need to track down a payment without the ID number, you run search_payments, letting your agent filter results using criteria like email address or date range.
Handling Refunds and Records
If something goes wrong, issuing money back is simple. You trigger a refund for any existing payment by calling refund_payment with the payment ID, specifying if you want a full or partial amount returned. If your agent pulls up general customer info via get_customer, it provides all the records necessary to process these actions.
You handle every step—registration, linking, charging, finding, and refunding—all through natural language commands right in your chat interface.
How Mercado Pago MCP Works
- 1 Subscribe to the server and provide your Mercado Pago Access Token.
- 2 Your AI client connects, authenticating the necessary API credentials for payment operations.
- 3 You instruct the agent (e.g., 'Refund transaction 12345'). The tool executes the request and returns a status confirmation.
The bottom line is: you connect your unique access token to the client, and then you manage all payment operations using chat prompts.
Who Is Mercado Pago MCP For?
This server is built for anyone dealing with high-volume e-commerce transactions in Brazil. It's for the ops manager who hates clicking through ten different tabs just to process a refund, or the small business owner who needs to take payments without hiring a dedicated developer.
Processes refunds and handles order management by instructing the agent directly in chat, avoiding the need to log into the payment portal.
Integrates Pix payments and card processing logic into complex AI-driven financial workflows using specific tool calls like create_pix_payment.
Generates payment links or tracks sales history by asking simple questions, cutting out the need for custom coding to handle basic transactions.
What Changes When You Connect
- Process immediate refunds without leaving your client. Use
refund_paymentto instantly issue partial or full credits for any transaction ID you provide. - Generate instant payment QR codes using
create_pix_payment. This is ideal for cash-like transactions where the customer needs a quick, scannable code. - Keep track of every sale. Running
search_paymentslets you pull up reports and reconcile payments by email or status in minutes. - Handle new buyers effortlessly. Call
create_customerfirst, then usecreate_cardto save their payment method for one-click purchases later on. - Streamline checkout setup using
create_preference. This generates the secure link you need before a customer can complete their purchase.
Real-World Use Cases
The Return Request
A customer calls about a damaged item. Instead of having to manually check the order ID and then go to the payment portal, you ask your agent: 'Refund transaction 98765 fully.' The refund_payment tool executes it immediately, giving the customer confirmation right away.
The Bulk Reconciliation
At the end of the day, you need to match bank deposits against sales. You prompt: 'Show all approved payments from last week for user@email.com.' The agent uses search_payments and pulls a clean list detailing payment IDs and amounts.
The Instant Sale
A small vendor is selling goods at a local market. Instead of needing a physical terminal, they ask their agent to 'Create a Pix payment for R$350.' The create_pix_payment tool generates the QR code instantly for the buyer to scan.
The New Client Onboarding
A new client needs to pay, but you can't process a payment until you have their details. You first use create_customer to register them, then create_card to save the token for future one-click payments.
The Tradeoffs
Assuming universal card acceptance
Trying to process a payment just because it's a credit card, without knowing if the customer has already saved their details or what methods are available.
→
Before calling create_payment, run list_payment_methods to confirm support. If you need to save a card for later use, call create_card first.
Searching without filters
Asking the agent only 'Show all payments.' This results in an overwhelming list of every transaction ever recorded.
→
Always refine your search. Use search_payments and include a filter like status, email, or date range to narrow down the result set.
Mixing up customer data
Attempting to refund a payment without first verifying the associated customer's details.
→
Use get_customer with the known ID or email address. This ensures you have verified account information before initiating financial actions.
When It Fits, When It Doesn't
You should use this server if your primary need is to manage complex, high-volume transactions in the Brazilian payment ecosystem via an AI client. You must use it when handling Pix payments or requiring structured refunds because of the dedicated create_pix_payment and refund_payment tools.
Don't use this server if you only need simple data logging (use a general database tool instead). Also, don't rely on it for anything outside Brazil; its payment methods are specific to Mercado Pago. If your goal is merely reading basic user profiles without transactional intent, get_customer works, but remember that the core value here lies in executing financial actions.
Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Mercado Pago. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.
VINKIUS INFRASTRUCTURE
Cloud Hosted
Managed infra
V8 Isolated
Sandboxed per request
Zero-Trust Proxy
No stored credentials
DLP Enforced
Policy on every call
GDPR Compliant
EU data residency
Token Compression
~60% cost reduction
Works with Claude, ChatGPT, Cursor, and more
The Model Context Protocol standardizes how applications expose capabilities to LLMs. Instead of operating in isolation, your AI gains direct access to external platforms, live data, and real-world actions through secure, standardized connections.
This server provides 12 capabilities that interface natively with Claude, ChatGPT, Cursor, and any MCP client. No middleware. No custom integration required.
Available Capabilities
Handling customer payments used to mean jumping between dashboards and forms.
Today, processing a refund is a multi-step nightmare. You have to log into your admin panel, find the order by email or ID, navigate through transaction history tabs, confirm the payment amount, and then manually hit 'Issue Refund.' It's tedious clicking, copy-pasting, and context switching.
With this MCP server, you just ask the agent: 'Refund transaction 12345 for R$50.' The `refund_payment` tool runs the whole sequence—finding the payment, calculating the refund, and initiating the API call—all in one prompt.
Mercado Pago MCP Server: Control Payments via Conversation
Before this server, generating a checkout link meant going to the developer portal, setting up parameters, and waiting for the system to generate a URL you had to copy-paste into your site. Tracking those links required checking status pages.
Now, calling `create_preference` gives you the necessary payment link immediately through chat. You get the token right away; no manual steps are involved.
Common Questions About Mercado Pago MCP
How do I generate a Pix QR Code using create_pix_payment? +
You call create_pix_payment and provide the amount in BRL. The tool returns the necessary QR code data that your system can display for instant customer scanning.
Can I refund a payment using refund_payment if I don't know the exact ID? +
The refund_payment tool requires a Payment ID. If you only have an email, first use search_payments to find the correct transaction ID before running the refund command.
What is the difference between create_preference and create_payment? +
create_preference builds a secure web link for the customer to complete the purchase outside of chat. create_payment charges the card directly within the agent's workflow.
How do I find payments by email using search_payments? +
Use search_payments and pass 'email' as a filter criterion, along with the customer's email address. This function is designed for reconciliation reporting.
How does the `create_card` tool handle sensitive payment information securely? +
The data is tokenized immediately upon submission, ensuring compliance with PCI standards. Your AI client never handles raw card numbers; it only works with secure tokens generated by Mercado Pago's system.
Before using `create_customer`, how do I confirm the correct Brazilian identification format? +
Use the get_identification_types tool first. This lists all accepted formats—like CPF and CNPJ—so you can validate customer input before trying to register them with create_customer.
If a transaction fails, how can I use the `get_payment` tool to diagnose the exact error code? +
The get_payment tool returns detailed status codes and failure reasons. Pass in the payment ID, and it provides the specific merchant-level error message, helping you pinpoint if the issue is insufficient funds or a declined card type.
When should I use the `create_preference` tool instead of directly calling `create_payment`? +
Use create_preference when you need a redirectable checkout link, typically for embedding on a website. It sets up the entire transaction context first, allowing multiple steps before payment capture.
How do I get a Mercado Pago Access Token? +
Go to your Mercado Pago account, navigate to Developers > Your Integrations > Production Credentials (or Sandbox), and copy your Access Token. It starts with 'APP_USR-' for production.
Can I generate Pix payments? +
Yes! Use the create_pix_payment action. It generates a Pix transaction and returns QR Code data that can be displayed for the payer to scan and pay instantly.
Can I issue refunds? +
Yes! Use the refund_payment action with a payment_id. If you omit the amount, it performs a full refund. If you provide an amount, it performs a partial refund.
Use it with your favorite AI tools
Connect this server to Cursor, Claude, VS Code, and more.
More in this category
Bolt
Manage your one-click checkout and payments via Bolt — track transactions, manage orders, and process refunds directly from any AI agent.
GoCardless
Manage direct debit payments, track mandates, and oversee customers via AI agents with GoCardless.
Banco Inter
Connect to your Banco Inter Empresas digital account. Automate Pix, Boletos, balance inquiries and statements.
You might also like
Userback
Collect visual feedback from users with annotated screenshots, screen recordings, and bug reports embedded in your product.
Chattermill
Analyze customer feedback and sentiment via Chattermill — track AI-powered themes, monitor NPS and CSAT, and unify feedback from every channel directly from any AI agent.
ZenQuotes API
Access inspirational quotes — audit random and daily quotes via AI.