MCP - Technical User Guide

Use the MoneyHash MCP server to look up your payment data from any AI assistant that supports MCP. Ask about an intent, a transaction, a customer, or a provider response, and the assistant fetches the answer from MoneyHash.

The server is read-only. It cannot create, update, capture, or refund a payment.

Typical questions:

• "Why did payment intent <INTENT_ID> fail?"
• "What did the provider return for transaction <TRANSACTION_ID>?"
• "List [email protected]'s payments this month. How many failed?"
• "Was the webhook for this payment delivered?"

What you can query

When to use it

How it works

Your AI assistant (the MCP client) sends each request over HTTP with your token. The MoneyHash MCP server checks the token, reads only your organization's data, and returns the result to the assistant. The client never calls the MoneyHash API directly.

Step 1: Get an API token

MCP access is set up for you by MoneyHash. You do not create tokens yourself.

1. Contact your MoneyHash account manager or support and ask for MCP access.
2. MoneyHash creates a token for your organization and sends it to you through a secure channel.
3. Store the token in a secrets manager or the client's config file. Do not paste it into tickets, chats, or shared documents.
   Each token is created for one mode:

Both modes run on MoneyHash production and use the same server URL. To query the other mode, ask MoneyHash for a token of that type.

Keep in mind:

• Tokens are scoped to one organization and cannot access any other organization's data.
• Tokens expire after 90 days. Ask MoneyHash for a new one and replace it in your client config.
• Treat the token as a secret. If it is exposed, contact MoneyHash immediately so it can be revoked.

Step 2: Connect your client

The server uses MCP over HTTP. Every client needs the same two values:

Restart the client after adding the config so the MoneyHash tools load.

There are two ways to connect, depending on what your client supports:

If your client accepts a server URL and headers, use Option A. If it only accepts a command to run, as Claude Desktop does, use Option B.

Option A: Direct HTTP

Cursor

Add to ~/.cursor/mcp.json (or Settings → MCP):

{
  "mcpServers": {
    "moneyhash": {
      "type": "http",
      "url": "https://agentic.moneyhash.io/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_TOKEN>" }
    }
  }
}

Claude Code

claude mcp add --transport http moneyhash \
  https://agentic.moneyhash.io/mcp \
  --header "Authorization: Bearer <YOUR_API_TOKEN>"

Run /mcp to confirm the server loaded.

ChatGPT / Codex

Add MoneyHash as a custom MCP server using the server URL and bearer token above. From the Codex CLI:

codex mcp add moneyhash --url https://agentic.moneyhash.io/mcp \
  --header "Authorization: Bearer <YOUR_API_TOKEN>"

VS Code

Add to .vscode/mcp.json. VS Code uses servers, not mcpServers:

{
  "servers": {
    "moneyhash": {
      "type": "http",
      "url": "https://agentic.moneyhash.io/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_TOKEN>" }
    }
  }
}

Option B: Local bridge for Claude Desktop

Claude Desktop starts MCP servers as local programs. It does not accept a url entry in its config file, and skips it with the message "not valid MCP server configurations." mcp-remote is a small bridge that Claude Desktop starts locally and that forwards to the MoneyHash server. It runs through npx, which comes with Node.js. Install Node.js (LTS) first if npx is not already on your machine.

1. In Claude Desktop, open the Claude menu in your system menu bar (not the settings inside the chat window), then Settings → Developer → Edit Config. This opens claude_desktop_config.json.
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the mcpServers block below at the top level of the file, next to any existing keys. Do not put it inside preferences. If the file already has an mcpServers object, add moneyhash inside it.

{
  "mcpServers": {
    "moneyhash": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agentic.moneyhash.io/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_API_TOKEN>"
      }
    }
  }
}

3. Fully quit Claude Desktop (Cmd+Q on macOS, not just closing the window) and reopen it.

Other clients

Any MCP client that supports HTTP servers works. Point it at https://agentic.moneyhash.io/mcp and send the token as a bearer token in the Authorization header.

Step 3: Run your first query

Every query runs against one account and one environment.

• Mode: set by the token. A live token reads live-mode data and a test token reads test-mode data, both on MoneyHash production. To query the other mode, use a token of that type.
• Account: every account-level tool takes an account ID. If the assistant asks for one, copy it from the MoneyHash Dashboard under Settings → Accounts and include it in your prompt.
  Example session:

On account <ACCOUNT_ID>, get payment intent <INTENT_ID> and explain why it failed.
 
Show the provider interactions for the failed transaction.

More examples:

• "Was this a provider decline, or did it fail before reaching the provider?"
• "Find [email protected] and list their recent transactions."
• "Which providers are connected to account <ACCOUNT_ID>?"
• "Was a webhook sent for transaction <TRANSACTION_ID>, and was it delivered?"

Tool reference

All tools are read-only. Parameter names below are exactly as the server exposes them. List-style tools accept optional page and page_size.

Analytics

getAnalytics returns the same numbers your Dashboard shows for the same filters. It is read-only.

• Only provider and method are breakdowns. Everything else is a filter. To split by currency, run one query per currency.
• If the response is flagged empty, there is no data for that filter. It does not mean 0%.
• Names are shown exactly as returned. Blank or UNKNOWN values are not interpreted.

Limits and behavior

Troubleshooting

FAQ