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, an access token, or an Apidog account to use it.
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://kushki-mcp-public-gateway-tbvc3yl6ja.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
Prerequisites#
Before you begin, make sure you have the following:An MCP-compatible AI assistant, such as Claude, Claude Code, Cursor, Windsurf, or VS Code with an extension that supports MCP.
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.
Choose a connection method#
There are three ways to connect the server. Choose the first one that your assistant supports:| Method | When to use it | Requirements |
|---|
| 1. Custom connector | Your assistant lets you add remote servers from its own interface. This is the fastest option. | None |
| 2. Streamable HTTP | Your assistant is configured through a JSON file. | None |
3. mcp-remote bridge | Your assistant only supports local servers. | Node.js 18 or later |
The three methods connect to the same server and give you the same information.You only need to configure the server once. The URL stays in sync with the published documentation, so every time we update it, your assistant will access the latest version without any changes to your configuration.
Option 1: Add the server as a custom connector#
This is the easiest way to connect, because you only paste the URL into the interface of your assistant. You do not edit files or install dependencies.Follow these steps to add the connector in Claude Desktop or in
claude.ai:
1.
Go to Settings > Connectors.
2.
Select 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. The connector will appear in the list as available.
http transport. This configuration does not require Node.js or any local installation.These are the steps to follow:1.
Copy the JSON configuration shown below.
2.
Paste the configuration into your assistant's MCP file and save the changes. Find the exact file location for each tool in the next section. 3.
Restart your AI assistant so it loads the MCP server.
4.
Verify the connection with a test prompt, for example: "Fetch the Kushki Peru documentation via MCP and tell me which fields are required to create a card charge." If the assistant returns correct information about the Kushki API, the connection was successful.
{
"mcpServers": {
"kushki-apis": {
"type": "http",
"url": "https://kushki-mcp-public-gateway-tbvc3yl6ja.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp"
}
}
}
The mcp.json file that VS Code uses for Copilot expects the servers key instead of mcpServers. If you edit that file manually, keep the same content and only replace the name of the main key. Cline and the rest of the assistants do use mcpServers.
Configuration file location#
Below you will find where each assistant's MCP file is located and how to open it.These are the steps to add the configuration in Claude Desktop:
1.
In the menu bar, go to Claude > Settings.
2.
Select the Developer tab.
3.
Click the Edit Config button. The location of the claude_desktop_config.json file will open. If the file does not exist, this option creates it automatically.
4.
Open the file with your text editor, paste the configuration, and save the changes.
5.
Quit Claude Desktop completely and open it again.
| Operating system | Path |
|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
If your file already contains other MCP servers#
If the configuration file already contains other servers inside mcpServers, add only the inner block "kushki-apis": { ... }, separated from the previous server by a comma.Keep a single mcpServers 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://kushki-mcp-public-gateway-tbvc3yl6ja.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp"
}
}
}
Option 3: Connect through the mcp-remote bridge#
Some older versions of assistants only support local MCP servers. In that case, use the mcp-remote package as a bridge: it runs on your machine and translates the connection to the remote server.This is the only method that requires Node.js version 18 or later, preferably the latest LTS (Long Term Support) version. If your assistant supports option 1 or option 2, you do not need to install Node.js.
{
"mcpServers": {
"kushki-apis": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://kushki-mcp-public-gateway-tbvc3yl6ja.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp"
]
}
}
}
Verify your connection#
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 there is a single mcpServers key, that a comma separates each block, and that no quotation marks are missing. An invalid JSON file makes the assistant ignore the entire configuration.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:If the response includes the list of available tools, the server is working correctly and the problem is in your local configuration or in 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.