How to Connect MerchantSpring to Claude Desktop (MCP Setup Guide)

Method	Recommended For	Updates
Method 1 – Install using MCP file (.mcpb / .dxt)	Most users	Requires installing a new file for updates
Method 2 – Configure via MCP config file	Technical users	Updates automatically when new features are released

We recommend Method 1 for most users.

Method 1 (Easier) using the .dxt / .mcpb file:

Attached below here is an executable file that clients can use to access the MCP server, this file contains a specific version of our MCP server, it is not auto-updated and will require a file with a newer version of this to be executed again to update the server.

It is a one click install method for clients to be able to access the server

Prerequisites:

• A Anthropic claude pro subscription (as a minimum, higher tiers are also acceptable)

• Claude desktop application installed on MacOS or Windows machineDownload Claude | Claude by Anthropic

• Claude desktop must be open already before running executable

• The executable file here: https://help.merchantspring.io/hubfs/merchantspring-mcp-v1.1.4.mcpb?hsLang=en

How to install:

1. Open Claude desktop

2. Either execute the file (By double clicking on right click and open the file) or drag the file into claude desktop

3. Users shall then be greeted by this screen:

 

 4. Click install and confirm the installation

 

5. After installation is finished user will be prompted to enter their API key for api gateway, this should be gotten from our official api gateway site here: https://developer.merchantspring.io/dashboard 

 

6. After entering the key, ensure the user enables the MCP server: 

7. Users should now see the MCP server inside of their options on the chat bar here, and it should be automatically used by the LLM

 

Method 2: Configure MCP via Configuration File (Advanced)

This method requires editing Claude’s MCP configuration file.

The advantage is that the MCP server will automatically update when new features are released, so you won’t need to install new files.

Prerequisites

Before starting, ensure you have:

• Node.js version 20 or higher (https://formulae.brew.sh/formula/node)

• NPX installed (included with Node.js)

• A text editor

• An MCP-compatible client, such as:

  • Claude Desktop

  • Cursor

  • Other MCP-supported tools

   

Step 1: Generate Your API Key

Create an API key from the MerchantSpring Developer Portal: https://developer.merchantspring.io/dashboard

You will need this key for the configuration file.

Step 2: Open Claude’s MCP Configuration

In Claude Desktop, navigate to: Settings → Developer → Edit Config

This opens the configuration file.

File locations

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3: Add the MerchantSpring MCP Configuration

Add the following configuration to your file.

If no other MCP servers exist, you can replace the entire file.

{
  "globalShortcut": "",
  "mcpServers": {
    "merchantspring-remote": {
      "command": "npx",
      "args": [
        "-p", "node@22",
        "-p", "mcp-remote@latest",
        "--",
        "mcp-remote",
        "https://mcp.merchantspring.io/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <user-api-key-goes-here>"
      }
    }
  }
}

Replace: <user-api-key-goes-here> with your MerchantSpring API key.

⚠ Important

• Do not include the < > brackets

• Keep the Bearer prefix
  
  Example: "AUTH_HEADER": "Bearer abc123xyz456"
  
  

Step 4: Restart Claude Desktop

After saving the file:

1. Close Claude Desktop

2. Reopen the application

You should now see an MCP indicator in the chat input area.

Click it to view available MCP tools.

Troubleshooting

If the MCP server does not appear:

1. Restart Claude Desktop

Most issues are resolved by restarting the app.

2. Check the configuration file

Ensure the JSON format is valid.

Incorrect syntax will prevent the MCP server from loading.

3. Check Claude logs

Mac: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs
Look for files beginning with: mcp*.log

Node / NPX Issues (Windows)

If you encounter Node-related errors:

Install npm globally: npm install -g npm
Also confirm this directory exists: %APPDATA%\npm

Security Notice

MCP servers can execute code locally on your machine.

Only install MCP servers from trusted sources and review documentation before enabling them.

Tip:

If you’re unsure which installation method to use, we recommend Method 1 (.mcpb install) for the fastest setup.