Kushki MCP Server#
Connect your AI assistant to the official Kushki API documentation.AI assistants have become a key tool for speeding up payment integrations. That is why, at Kushki, we publish the official specifications of our API as an MCP server. This way, tools like Claude or Cursor read the current documentation of each country directly, instead of relying on their prior knowledge or on fragments you copy by hand.In this guide, you will learn what MCP is, how to connect it to your AI assistant, and how to take advantage of it in your Kushki integration.This server only exposes our public documentation. You do not need Kushki credentials or an Apidog account to use it. The first time it connects, your assistant completes an automatic authorization handshake with the server: there is no login form and you are not asked for any data. Some assistants open a browser tab for a moment, or show a one-time Connect or Authenticate button.
What is MCP?#
MCP (Model Context Protocol) is an open protocol that connects AI assistants with external data sources. It works as a standardized communication channel: the assistant queries the information directly at the source, and returns answers based on what the documentation says today.At Kushki, we publish a single remote MCP server that covers the documentation of our five markets: Mexico, Peru, Colombia, Ecuador, and Chile. The server reads the official specifications published on our documentation portal, which means the AI knows our real endpoints, schemas, and parameters. As a result, it generates code, data models, and answers aligned with the current version of the documentation.This is the address of the Kushki MCP server:https://apidocs-mcp.kushki-docs.workers.dev/
The MCP server syncs with our documentation portal every 24 hours. If we publish a change to the documentation, it can take up to a day to be reflected in the server's answers. For very recent updates, check the documentation of the corresponding country in our documentation portal. Prerequisites#
Before you begin, make sure you have the following:An MCP-compatible AI assistant, such as Claude, Claude Code, Cursor, VS Code, or Cline.
The latest version of that assistant. Support for remote servers is included in current versions and keeps improving with each release.
An internet connection, since your assistant queries the documentation in real time.
An MCP server is a data source, not an assistant: it has no interface of its own. Connecting it only gives your assistant access to our documentation, so you always query it from the chat of the tool you already use.
Connect your assistant#
Find your tool in the tabs below and follow its steps. Every route connects to the same server and gives you the same information, and you only need to configure it once: the URL stays in sync with the published documentation, so your assistant will access the most recent synced version without any changes to your configuration.In Claude, you add the server as a custom connector. This works both in Claude Desktop and in
claude.ai, and it does not require you to edit files or install anything.
1.
Go to Customize > Connectors. In some versions of Claude Desktop, this option is under Settings > Connectors.
2.
Select + and then Add custom connector.
3.
In the Name field, enter Kushki APIs.
4.
In the URL field, paste the address of the Kushki MCP server.
5.
Confirm with Add. Claude completes the authorization on its own and the connector appears in the list as available.
6.
Open a new chat, display the connectors menu, and check that Kushki APIs is enabled.
On the Free plan you can keep one custom connector. The Pro, Max, Team, and Enterprise plans do not have that limit. In Team and Enterprise organizations, an owner adds the connector from Organization settings > Connectors, and then each member enables it from their own Connectors page.
If your file already contains other MCP servers#
If the configuration file already contains other servers, add only the inner block "kushki-apis": { ... }, separated from the previous server by a comma, and keep the block of your own tool.Keep a single main key in the file. If you duplicate it, the JSON will become invalid and your assistant will ignore the entire configuration.
{
"mcpServers": {
"another-server": {
"command": "npx",
"args": ["-y", "another-package@latest"]
},
"kushki-apis": {
"type": "http",
"url": "https://apidocs-mcp.kushki-docs.workers.dev/"
}
}
}
Verify your connection#
To confirm that everything works, ask your assistant a test question, for example: "Fetch the Kushki Peru documentation via MCP and tell me which fields are required to create a card charge." If the answer returns correct information about the Kushki API, the connection was successful.If your assistant does not respond with information from our documentation, check the following points.The server does not appear in the list#
Quit the assistant completely and open it again. Editing the configuration file is not enough, because the servers load at startup.The assistant reports a configuration error#
Review that the main key appears only once, that a comma separates each block, and that no quotation marks are missing. An invalid JSON file makes the assistant ignore the entire configuration.Also check that you copied the block from the tab of your own tool. The name of the main key and the value of the type field are not interchangeable between assistants.The server appears as pending authorization#
Select the server in your assistant's MCP panel and confirm the authorization. It is an automatic handshake that does not ask you for credentials.If you connected the server with mcp-remote and it stops responding, delete the ~/.mcp-auth folder and restart your assistant so it repeats the handshake.The assistant answers without using the server#
Mention the server explicitly in your prompt, for example: "Using the Kushki MCP server, look up...".The connection fails from your network#
Run the following command in your terminal to confirm that the server responds:The expected response is 401. That code confirms that the server is online and requesting the authorization that your assistant completes on its own, so the problem is in your local configuration. If you get a timeout or a network error instead, review your network's outbound rules.Use cases with Kushki#
Once the MCP server is connected, your AI assistant works with the real specification of our API. Mention the country in your prompts so the assistant finds the right documentation. These are some prompts you can use as a starting point:"Fetch the Kushki Mexico documentation via MCP and list the available endpoints for card payments."Generate integration code"Based on the Kushki Peru specification, generate the Node.js code to request a card token and then create a one-time charge.""Read the schema of the Kushki Colombia charges endpoint and generate the TypeScript interfaces for the request and the response.""Explain the two-step authorization and capture flow according to the Kushki Chile documentation and generate an example in Python.""List the documented error codes for the Kushki Ecuador refund endpoint and suggest how to handle them in my application.""Compare the required fields to create a card charge in Kushki Mexico and in Kushki Peru, and tell me the differences."Update an existing integration"Compare my current card charge implementation with the current Kushki specification and tell me which fields I am missing."The assistant answers based on our documentation, but it does not replace it. Before going live, validate the fields and flows of your integration against the reference of the corresponding country.
Kushki Developers
Explore our payment solutions for each market.Model Context Protocol
Learn how the open protocol behind this integration works.