Calypso MCP for merchants

Calypso MCP gives merchants read-only access to Calypso Public API data directly from AI tools that support MCP, such as Codex, Claude, Cursor, or other compatible clients.

With this integration, a merchant can ask an AI assistant to check accounts, currencies, invoices, deposits, wallets, and reports without writing direct API requests manually.

The MCP server uses the merchant Public API credentials and prepares required technical request data internally. For example, the request timestamp is computed automatically by the server.

What MCP Is

MCP, or Model Context Protocol, is a standard way to connect AI assistants to external tools and business systems.

In the Calypso case, MCP works as a controlled read-only gateway between an AI assistant and Calypso Public API. The assistant receives a list of available tools and can call them only when the merchant asks for information.

What Merchants Can Do

The current Calypso MCP integration exposes read-only tools. It is intended for analysis, support, reconciliation, and operational checks.

Available scenarios:

Scenario	What the assistant can help with
Account discovery	Get information about the current API user and available accounts.
Currency reference	Check supported crypto and fiat currency codes before using them in reports or lookups.
Invoice lookup	Find a specific invoice by system ID or idempotency key.
Invoice deposit lookup	Check a specific deposit transaction for an invoice.
Wallet lookup	Get settlement wallet information by address.
Balance and transaction checks	Review balances, rates, wallet transactions, incoming transactions, exchanges, and settlement reports.
Invoice reports	Build invoice reports for selected accounts, currencies, dates, and timezone.
Payout reports	Build payout reports for selected accounts, currencies, dates, and timezone.
Customer purse reports	Build customer purse reports to reconcile deposits by customer, purse address, transaction, and compliance state.
Customer and purse lookup	Review customer, purse, and customer transaction information.
Fiat order reference	Check fiat deposit and withdrawal order, geo, currency, and method information.
Webhook review	Review webhook subscriptions.

The MCP integration does not create invoices, create payouts, move funds, change settings, or modify merchant data.

Available Tools

Calypso MCP provides read-only tools generated from Calypso Public API. The exact tool schema is exposed by the MCP server to the AI client, so the assistant can see required parameters, allowed enum values, and response structure before calling a tool.

The integration includes 64 read-only tools across these areas:

Area	Examples
Account	`getAccount`, `getCurrentUser`
Currencies	`getCurrencies`, `getFiatCurrencies`, `getCryptoCurrenciesFullInfo`
Rates and fees	`getRates`, `getFiatRates`, `getFeeExtended`, `getAvailableOpcodes`
Invoices	`getInvoice`, `getInvoices`, `getInvoicesByExternalId`, `getInvoiceDepositHistory`, `getInvoiceDeposit`, `getInvoicePaymentHistory`, `getInvoicePayment`
Payouts	`findDeal`, `findDeals`, `findDealWithdrawal`, `findDealWithdrawals`, `findMassDeal`, `findMassDeals`
Settlement payouts	`getPayout`, `getPayouts`, `getPayoutWithdrawal`, `getPayoutWithdrawals`, `getMassPayout`, `getMassPayouts`
Exchange	`preCalculateExchange`, `getExchange`, `findExchangeByFilter`, `getCurrencyPair`, `getLimit`, `getAverageRate`
Reports	`buildBalanceReport`, `buildIncomingTransactionsReport`, `buildExchangeTransactionsReport`, `buildFiatReport`, `buildInvoiceReport`, `buildPayoutReport`, `buildCustomerPurseReport`
Settlement reports	`buildSettlementIncomingReport`, `buildSettlementOutgoingReport`, `buildSettlementAllReport`, `buildSettlementBalanceReport`
Settlement wallets	`getSettlementWalletTransactions`, `getSettlementWallets`, `getSettlementWallet`
Customers and purses	`getCustomer`, `getCustomerByExternalId`, `getPurseAddress`, `getPurses`, `getCustomerTransaction`, `getCustomerTransactions`
Fiat deposit and withdrawal	`getFiatDepositOrder`, `getFiatDepositCurrencies`, `getFiatDepositMethod`, `getFiatWithdrawalOrder`, `getFiatWithdrawalGeo`, `getFiatWithdrawalMethod`
Widgets and webhooks	`findSingleFiatWidget`, `findAllSingleFiatWidgets`, `findUnlimitedLinkedWidget`, `findAllUnlimitedLinkedWidgets`, `getSubscriptions`

Authentication

Calypso MCP uses the same Public API credentials that merchants create in the Calypso dashboard.

API keys are account-scoped. Each key is created for a specific account inside the merchant company and should be used only with that account. If your company has several accounts, create a separate API key for the account you want to connect to MCP.

Before connecting MCP, create API keys in Calypso UI:

how-to-create-new-api-key.md

For MCP analytics scenarios, create a key with Read access level when this option is available in your Calypso dashboard. Read-only keys are enough for the current MCP tools because Calypso MCP does not create invoices, create payouts, move funds, or change settings.

Required credentials:

Header	Description
`Key`	Public API key from the Calypso dashboard.
`Secret`	Secret API key from the Calypso dashboard.

The merchant should keep both values private. Do not publish them in source code, screenshots, public repositories, or shared prompts.

Unlike direct Public API integration, the MCP client does not need to pass timestamp manually. The MCP server computes it automatically.

The MCP server also prepares the signed Public API request internally. The Secret is used only to sign the request and should never be pasted into prompts or shared with an assistant as plain text.

Basic MCP Configuration

Use this JSON as a generic MCP configuration example for clients that support remote HTTP MCP servers:

{
  "mcpServers": {
    "calypso-read-only": {
      "url": "https://api.calypso.money/mcp",
      "transport": "http",
      "http_headers": {
        "Key": "YOUR_PUBLIC_API_KEY",
        "Secret": "YOUR_PUBLIC_API_SECRET"
      },
      "description": "Calypso MCP — read-only access to invoices, payouts, reports, wallets, balances and other merchant data via Public API."
    }
  }
}

Use these values:

Configuration value	Description
`https://api.calypso.money/mcp`	Production Calypso MCP server URL.
`YOUR_PUBLIC_API_KEY`	Public API key from the Calypso dashboard.
`YOUR_PUBLIC_API_SECRET`	Secret API key from the Calypso dashboard.

Use credentials from the same account that you plan to pass in MCP tool calls. Credentials created for one account are not intended to work as universal credentials for all accounts in the company.

First Steps After Connection

After adding the MCP server to your AI client, start with these calls:

Ask the assistant to call getCurrentUser.
Select the required merchant account from the response.
Ask the assistant to call getCurrencies.
Ask the assistant to call getFiatCurrencies.
Use the selected account and currency codes in invoice, payout, wallet, and report requests.

Most business tools require account. If the account is missing, the tool cannot know which merchant account should be used.

The selected account must match the account for which the API key was generated.

Codex Setup Example

In Codex, add the MCP server to your MCP configuration.

Example JSON:

{
  "mcpServers": {
    "calypso-read-only": {
      "url": "https://api.calypso.money/mcp",
      "transport": "http",
      "http_headers": {
        "Key": "YOUR_PUBLIC_API_KEY",
        "Secret": "YOUR_PUBLIC_API_SECRET"
      }
    }
  }
}

If your Codex installation uses TOML configuration, the same connection can be represented like this:

[mcp_servers.calypso-read-only]
url = "https://api.calypso.money/mcp"
transport = "http"
http_headers = { "Key" = "YOUR_PUBLIC_API_KEY", "Secret" = "YOUR_PUBLIC_API_SECRET" }

Restart Codex or reload MCP servers after changing the configuration.

Codex Usage Examples

Check available accounts:

Use Calypso MCP and show me the current API user and available merchant accounts.

If you have not created API keys yet:

Open the Calypso documentation page about creating API keys in UI and explain how to generate read-only keys for MCP.

Check supported currencies:

Use Calypso MCP to get the list of supported cryptocurrencies and fiat currencies.

Find an invoice:

Use Calypso MCP to find invoice with idempotency key 1be6a518-6dcd-477d-96af-dd914b1300ce for account 0x123...

Build an invoice report:

Use Calypso MCP to build an invoice report for account 0x123... for USDT and BTC from 2026-07-01 to 2026-07-09 with timezone +03:00.

Build a payout report:

Use Calypso MCP to build a payout report for account 0x123... for USDT from 2026-07-01 to 2026-07-09 with timezone +03:00.

Build a customer purse report:

Use Calypso MCP to build a customer purse report for account 0x123... for USDT from 2026-07-01 to 2026-07-09 with timezone +03:00. Summarize deposits by customer and compliance state.

Check a settlement wallet:

Use Calypso MCP to get settlement wallet information for account 0x123... and address TExampleAddress...

Claude Setup Example

For Claude clients that support remote HTTP MCP servers, add Calypso MCP to the MCP server list.

Example configuration:

{
  "mcpServers": {
    "calypso-read-only": {
      "url": "https://api.calypso.money/mcp",
      "transport": "http",
      "http_headers": {
        "Key": "YOUR_PUBLIC_API_KEY",
        "Secret": "YOUR_PUBLIC_API_SECRET"
      }
    }
  }
}

Restart Claude or reload MCP servers after saving the configuration.

Claude Usage Examples

Ask for account discovery:

Using Calypso MCP, get my current user information and list the accounts I can use.

Ask for a report:

Using Calypso MCP, build an invoice report for account 0x123... for USDT from 2026-07-01 to 2026-07-09. Use timezone +03:00.

Ask for invoice status:

Using Calypso MCP, check invoice id 3fa85f64-5717-4562-b3fc-2c963f66afa6 for account 0x123... and summarize its current state.

Ask for payout analysis:

Using Calypso MCP, build a payout report for account 0x123... for USDT and summarize completed, failed, and in-progress payouts.

Ask for customer deposit reconciliation:

Using Calypso MCP, build a customer purse report for account 0x123... for USDT from 2026-07-01 to 2026-07-09. Group deposits by customer external ID and highlight declined compliance checks.

Practical Merchant Scenarios

1. Daily Payment Monitoring

Goal: understand invoice activity for the day.

Example prompt:

Use Calypso MCP to build an invoice report for account 0x123... for USDT from 2026-07-09 to 2026-07-09 with timezone +03:00. Summarize total invoice activity and highlight anything that needs attention.

Expected MCP tool:

buildInvoiceReport

Required parameters:

{
  "account": "0x123...",
  "currencyList": ["USDT"],
  "firstDate": "2026-07-09",
  "lastDate": "2026-07-09",
  "zoneOffset": "+03:00"
}

2. Payout Reconciliation

Goal: compare payout activity for a selected period.

Example prompt:

Use Calypso MCP to build a payout report for account 0x123... for USDT from 2026-07-01 to 2026-07-09 with timezone +03:00. Group the result by payout status.

Expected MCP tool:

buildPayoutReport

Required parameters:

{
  "account": "0x123...",
  "currencyList": ["USDT"],
  "firstDate": "2026-07-01",
  "lastDate": "2026-07-09",
  "zoneOffset": "+03:00"
}

3. Invoice Investigation

Goal: check what happened to a specific invoice.

Example prompt:

Use Calypso MCP to get invoice by idempotency key 1be6a518-6dcd-477d-96af-dd914b1300ce for account 0x123... Explain the invoice state and whether payment was received.

Expected MCP tool:

getInvoice

Required parameters:

{
  "account": "0x123...",
  "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce"
}

4. Invoice Deposit Investigation

Goal: check a specific deposit transaction for an invoice.

Example prompt:

Use Calypso MCP to get invoice deposit transaction 123dce78-2ca9-4e94-b657-5751c95cabd6 for invoice id 3fa85f64-5717-4562-b3fc-2c963f66afa6 and account 0x123...

Expected MCP tool:

getInvoiceDeposit

Required parameters:

{
  "account": "0x123...",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transactionId": "123dce78-2ca9-4e94-b657-5751c95cabd6"
}

5. Wallet Lookup

Goal: check settlement wallet information by address.

Example prompt:

Use Calypso MCP to get settlement wallet information for account 0x123... and wallet address TExampleAddress...

Expected MCP tool:

getSettlementWallet

Required parameters:

{
  "account": "0x123...",
  "address": "TExampleAddress..."
}

6. Currency Code Check

Goal: avoid using unsupported currency codes in reports or lookups.

Example prompt:

Use Calypso MCP to show supported cryptocurrencies and fiat currencies. I need the exact codes for USDT on Tron and EUR.

Expected MCP tools:

getCurrencies
getFiatCurrencies

Recommended Prompt Pattern

For best results, include:

Account ID.
Currency codes.
Date range.
Timezone offset.
Object identifiers, such as invoice ID, idempotency key, transaction ID, or wallet address.
What kind of summary you expect from the assistant.

Good prompt:

Use Calypso MCP to build an invoice report for account 0x123... for USDT_TRX from 2026-07-01 to 2026-07-09 with timezone +03:00. Summarize total paid invoices, pending invoices, and failed or suspicious cases.

Weak prompt:

Check my invoices.

The weak prompt does not include account, currency, date range, or expected result.

Security Recommendations

Use API keys created specifically for MCP access.
Create MCP API keys separately for each account that should be connected.
Prefer API keys with Read access level for MCP analytics and support scenarios.
Store Key and Secret only in the MCP client configuration or a secure secret manager.
Do not paste secrets into chat prompts.
Do not commit real credentials to Git.
Rotate API keys if they were exposed.
Review which team members have access to the AI client configuration.

Troubleshooting

Problem	What to check
MCP server is not visible in the AI client	Check that the MCP configuration file is valid JSON or TOML and restart the client.
Authentication fails	Check `Key` and `Secret` values. Make sure they were copied from the Calypso dashboard without extra spaces and belong to the account used in the request.
The key has more permissions than needed	Create a separate API key with `Read` access level for MCP, then replace the credentials in the MCP configuration.
Tool asks for `account`	First call `getCurrentUser` and use the account for which the configured API key was created.
Currency is rejected	Call `getCurrencies` or `getFiatCurrencies` and use the exact code returned by Calypso.
Report returns unexpected time period	Check `firstDate`, `lastDate`, and `zoneOffset`.
Invoice is not found	Check whether you are using `id` or `idempotencyKey`, and make sure the selected account is correct.

Full Example Configuration

{
  "mcpServers": {
    "calypso-read-only": {
      "url": "https://api.calypso.money/mcp",
      "transport": "http",
      "http_headers": {
        "Key": "YOUR_PUBLIC_API_KEY",
        "Secret": "YOUR_PUBLIC_API_SECRET"
      },
      "description": "Calypso MCP — read-only access to invoices, payouts, reports, wallets, balances and other merchant data via Public API."
    }
  },
  "usage": {
    "first_steps": [
      "1. Use https://api.calypso.money/mcp as the MCP server URL",
      "2. Replace YOUR_PUBLIC_API_KEY and YOUR_PUBLIC_API_SECRET with keys from your Calypso dashboard",
      "3. Call getCurrentUser to get the list of available accounts and select the account for which the key was created",
      "4. Call getCurrencies and getFiatCurrencies to learn available currency codes",
      "5. Pass account in every request where account is required"
    ],
    "timestamp_note": "The timestamp is computed automatically by the server. No need to pass it."
  }
}

What MCP Is​

What Merchants Can Do​

Available Tools​

Authentication​

Basic MCP Configuration​

First Steps After Connection​

Codex Setup Example​

Codex Usage Examples​

Claude Setup Example​

Claude Usage Examples​

Practical Merchant Scenarios​

1. Daily Payment Monitoring​

2. Payout Reconciliation​

3. Invoice Investigation​

4. Invoice Deposit Investigation​

5. Wallet Lookup​

6. Currency Code Check​

Recommended Prompt Pattern​

Security Recommendations​

Troubleshooting​

Full Example Configuration​

What MCP Is

What Merchants Can Do

Available Tools

Authentication

Basic MCP Configuration

First Steps After Connection

Codex Setup Example

Codex Usage Examples

Claude Setup Example

Claude Usage Examples

Practical Merchant Scenarios

1. Daily Payment Monitoring

2. Payout Reconciliation

3. Invoice Investigation

4. Invoice Deposit Investigation

5. Wallet Lookup

6. Currency Code Check

Recommended Prompt Pattern

Security Recommendations

Troubleshooting

Full Example Configuration