# MD for: https://www.mercadopago.com.uy/developers/es/docs/checkout-pro/additional-content/mcp-server/troubleshooting.md

\# Troubleshooting When working with Mercado Pago MCP Server, you may encounter issues that disrupt your workflow. This guide will help you quickly identify, diagnose and solve common errors, ensuring a smoother experience. If you are experiencing issues connecting to the MCP, follow these steps: :::AccordionComponent{title="Check your network connection"} Ensure your device is connected to the internet and that there are no blocks preventing access to the MCP Server endpoint (\`https://mcp.mercadopago.com/mcp\`). ::: :::AccordionComponent{title="Check your credentials"} To access the MCP Server, you need a valid credential. Call one of our public APIs to verify your credential, for example the:TagComponent{tag="API" text="/v1/payment\_methods" href="/developers/en/reference/online-payments/checkout-pro/payment-methods/get"}. See how it works in practice: \`\`\`bash curl -X GET "https://api.mercadopago.com/v1/payment\_methods" \\ -H "Authorization: Bearer " \`\`\` The expected outcome is: \`\`\`json \[ { "id": "visa", "name": "Visa", "payment\_type\_id": "credit\_card", "status": "active", "secure\_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/visa.gif", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/visa.gif", "deferred\_capture": "supported", "settings": { "card\_number": { "length": 16, "validation": "standard" }, "security\_code": { "mode": "mandatory", "length": 3, "card\_location": "back" } }, "additional\_info\_needed": \[ {} \], "min\_allowed\_amount": 0.5, "max\_allowed\_amount": 60000, "accreditation\_time": 2880, "financial\_institutions": {}, "processing\_modes": "aggregator" } \] \`\`\` If you receive a different response, your credentials may not be valid. If you need a new credential, follow our \[credentials documentation\](https://www.mercadopago.com.uy/developers/en/docs/credentials). ::: :::AccordionComponent{title="Verify Node.js version"} For most MCP clients (such as Cursor, Claude and Windsurf), Node.js 20 or higher is required. To check your current Node.js version, run: \`\`\`bash node -v \`\`\` The output will show the default Node.js version and it should be version 20 or higher. If you use NVM (Node Version Manager), run the following commands to check installed versions and, if necessary, install a new one: \`\`\`bash # List installed Node.js versions nvm list # Install Node.js 20 nvm install 20 # Uninstall a specific version (replace XX with the version number) nvm uninstall XX \`\`\` If the issues persist, ensure your Node.js and NPM installations are up to date. Then, check your npm version with: \`\`\`bash npm -v \`\`\` For more information, check out the \[NPX documentation\](https://www.npmjs.com/package/npx). ::: :::AccordionComponent{title="Check NPX installation"} NPX is a package runner tool bundled with NPM (Node Package Manager) that's used to connect to Mercado Pago MCP Server. ### Check NPX installation To check if NPX is already installed, run: \`\`\`bash npx --version \`\`\` If you see a version number, the package is installed. In case you get a "command not found" error, you need to install or upgrade npm (which includes npx). ### Install or upgrade NPX NPX is included with NPM version 5.2.0 and above. Run the following command to install or upgrade both packages (NPM and NPX): \`\`\`bash npm install -g npm \`\`\` After upgrading, verify the installation: \`\`\`bash npx --version \`\`\` If the issues persist, ensure your Node.js and NPM installations are up to date. Then, check your npm version with: \`\`\`bash npm -v \`\`\` For more information, check out the \[NPX documentation\](https://www.npmjs.com/package/npx). ::: :::::AccordionComponent{title="Check your client version"} To successfully connect with our MCP Server, it is important to always have the latest available version of the client you are using. To check this and, if necessary, update your version, follow the step-by-step instructions according to your preferred client. ::::TabsComponent :::TabComponent{title="Cursor"} To find out the latest available version of Cursor, check its \[\_Changelog\_\](https://cursor.com/changelog). Then, verify your application version according to your operating system. ### macOS You can check the version of Cursor you are using by going to \*\*Cursor > About Cursor\*\*. If it does not match the version indicated in the \_Changelog\_, you can force an update by accessing the the top menu again and clicking \*\*Cursor > Check for updates\*\*. This will guide you through the necessary steps. ### Windows You can check the version of Cursor you are using by going to the \*\*Help > About Cursor\*\* menu. If it does not match the version indicated in the \_Changelog\_, you can force an update by accessing the the top menu again and clicking \*\*Help > Check for updates\*\*. This will guide you through the necessary steps. ::: :::TabComponent{title="Windsurf"} To find out the latest available version of Windsurf, check its \[\_Changelog\_\](https://windsurf.com/changelog). Then, verify your application version according to your operating system. ### macOS You can check the version of Windsurf you are using by going to \*\*Windsurf > About Windsurf\*\*. If it does not match the version indicated in the \_Changelog\_, you can force an update by accessing the the top menu again and clicking \*\*Windsurf > Check for updates\*\*. This will guide you through the necessary steps. ### Windows You can check the version of Windsurf you are using by going to the \*\*Help > About Windsurf\*\* menu. If it does not match the version indicated in the \_Changelog\_, you can force an update by accessing the the top menu again and clicking \*\*Help > Check for updates\*\*. This will guide you through the necessary steps. ::: :::TabComponent{title="Other clients"} To check for updates in other clients, such as \*\*Claude Desktop\*\* or \*\*ChatGPT\*\*, look for the \*\*Check for updates\*\* option in the application's top menu. If an update is available, the application will notify you and allow you to install it. If you have any issues performing this update, you can also go to the official site of the client, download the latest version of the application, and replace it on your system. ::: :::: ::::: :::AccordionComponent{title="Terminal connection testing"} If connection issues persist, try connecting to the MCP Server through your terminal: \`\`\`bash npx -y mcp-remote@latest https://mcp.mercadopago.com/mcp --header 'Authorization:Bearer ' \`\`\` The expected output should look like this: \`\`\`text \[22599\] Using automatically selected callback port: 22476 \[22599\] Using custom headers: {"Authorization":"Bearer "} \[22599\] \[22599\] Connecting to remote server: https://mcp.mercadopago.com/mcp \[22599\] Using transport strategy: http-first \[22599\] Connected to remote server using StreamableHTTPClientTransport \[22599\] Local STDIO server running \[22599\] Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport \[22599\] Press Ctrl+C to exit \`\`\` Common errors at this stage: | Error | Description | |-|-| | \`\`\`ReferenceError: TransformStream is not defined\`\`\`| It means that you're using an outdated version of Node.js. Uninstall all versions except for one (version 20 or higher). | | \`\`\`command not found: npx\`\`\` | It means NPX is not installed on your system. Follow the instructions in the section \*\*Check NPX installation\*\* to solve this issue. | ::: :::::AccordionComponent{title="Test the connection via authentication header"} If you have issues connecting our MCP Server in Cursor or VS Code, try changing the authentication mode. To do this, follow the steps indicated for the client you are using. ::::TabsComponent :::TabComponent{title="Cursor"} To install our MCP in Cursor via authentication \_header\_, you can click the button below or follow the steps manually. \[!\[Install MCP Server\](https://cursor.com/deeplink/mcp-install-dark.svg)\](cursor://anysphere.cursor-deeplink/mcp/install?name=mercadopago-mcp-server&config=eyJ1cmwiOiJodHRwczovL21jcC5tZXJjYWRvcGFnby5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIDxBQ0NFU1NfVE9LRU4%252BIn19) Open the \`.cursor/mcp.json\` file and add the Mercado Pago server configuration. Check the \[Cursor documentation\](https://docs.cursor.com/context/model-context-protocol) for more information. Fill in the \`\` field with your :toolTipComponent\[\_Access Token\_\]{content ="Private key of the application created in Mercado Pago and used in the backend. You can access it through \*Your integrations\* > \*Application details\* > \*Tests\* > \*Test credentials\* or \*Production\* > \*Production credentials\*." title="Access Token"}. \`\`\`json { "mcpServers": { "mercadopago-mcp-server-prod": { "url": "https://mcp.mercadopago.com/mcp", "headers": { "Authorization": "Bearer " } } } } \`\`\` After completing these steps, Mercado Pago MCP Server should be ready to use. To verify if the integration was successful, access your client settings and confirm that the MCP is marked as available. ::: :::TabComponent{title="VS Code"} 1\. Open VS Code and press \*\*Cmnd + Shift + P\*\* if you use macOS, or \*\*Ctrl + Shift + P\*\* if you use Windows. This will position you in the search bar, located at the top margin, so you can search in your settings. 2\. Type \*\*MCP: Open User Configuration\*\*. The \`mcp.json\` file will automatically open, where you must add the Mercado Pago MCP Server configuration as shown below, completing the  field with your :toolTipComponent\[\_Access Token\_\]{content ="Private key of the application created in Mercado Pago and used in the backend. You can access it through \*Your integrations\* > \*Application details\* > \*Tests\* > \*Test credentials\* or \*Production\* > \*Production credentials\*." title="Access Token"}. \`\`\`json { "servers": { "mcp-mercadopago": { "command": "npx", "args": \[ "-y", "mcp-remote@latest", "https://mcp.mercadopago.com/mcp", "--header", "Authorization: Bearer " \], } } } \`\`\` 3\. Save the configuration and go to \*\*Extensions > MCP Servers - Installed\*\*, where you can view it. 4\. Click on its \*\*Settings\*\* and then on \*\*Start Server\*\*. The connection process will start, which you can follow from the console. When finished, Mercado Pago MCP Server will be ready to use. If there is any error in the process, it will be indicated and you can make the necessary adjustments. ::: :::TabComponent{title="Claude Code"} If you experience issues with OAuth authentication in Claude Code, you can connect using your :toolTipComponent\[Access Token\]{content ="Private key of the application created in Mercado Pago and used in the backend. You can access it through \*Your integrations\* > \*Application details\* > \*Tests\* > \*Test credentials\* or \*Production\* > \*Production credentials\*." title="Access Token"} manually. Use the following command: \`\`\`bash claude mcp add \\ --transport http \\ mercadopago \\ https://mcp.mercadopago.com/mcp \\ --header "Authorization: Bearer YOUR\_ACCESS\_TOKEN" \`\`\` Then, verify the connection by running: \`\`\`bash /mcp \`\`\` With this credential-based authentication method, no OAuth authentication window will open. The MCP will be available immediately after verification. ::: :::: :::::