MCP Connection — Developer Resources

Key Information

If you’re not an existing API client and would like use the HSBC Account and Transaction MCP, please contact your HSBC relationship representative to initiate onboarding. To help us process your request quickly, include your organisation name, intended use case, and the technical contact for setup.

If you are an existing HSBC Treasury API you may be able to get access, subject to eligibility. Please contact your HSBC representative for more details.

Server details

The MCP Server requires an OAuth bearer token for authentication. It uses a session-based flow: call initialize first, then reuse the mcp-session-id header in subsequent tools/list and tools/call requests.

Setting	Value
Server name	`mcp-server`
URL	`https://interact.hsbc.com/mcp`
Authentication	OAuth bearer token
Transport	Remote HTTP/SSE

Setup

Add the MCP Server to your AI tool. Replace YOUR_TOKEN with your OAuth bearer token. Select your client below for setup instructions.

Run the following command to add the MCP Server to Claude Code:

$ claude mcp add --transport http mcp-server https://interact.hsbc.com/mcp --header "Authorization: Bearer $MCP_TOKEN"

Alternatively, add the following to your .claude/settings.json or .mcp.json file:

{
  "mcpServers": {
    "mcp-server": {
      "url": "https://interact.hsbc.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Add the following configuration to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-server": {
      "url": "https://interact.hsbc.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Add the following configuration to .vscode/mcp.json in your workspace:

{
  "servers": {
    "mcp-server": {
      "type": "http",
      "url": "https://interact.hsbc.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

MCP is an open protocol supported by many clients. Use https://interact.hsbc.com/mcp as the server URL and include your OAuth bearer token in the Authorization header:

{
  "mcp-server": {
    "url": "https://interact.hsbc.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  }
}

Verify it works

After setup, ask your AI tool to call the get_nio_hello tool. If the server is connected correctly, you'll receive a greeting with the current server time. You can also ask your AI tool to list available MCP tools and confirm mcp-server appears.

Available tools

The following tools are available through the MCP Server:

Tool	Description
get_accounts_balances	List accounts or retrieve balances for the authenticated customer.
get_account_transactions	Transaction history for one or more accounts, with explicit or filter-based discovery.
get_fx_rates_and_conversion	FX rates, conversion, and historical rate series.
get_payments_status	Structured payment search by UETR, reference, amount, value date, currency, or account.
get_nio_hello	Connectivity/health check — returns a greeting with the current server time.

Service discovery

Each tool maps to an underlying service. The service key can be used for programmatic discovery and routing.

Tool	Service	Description
`get_accounts_balances`	`accounts`	List accounts or retrieve balances for the authenticated customer.
`get_account_transactions`	`transactions`	Transaction history for one or more accounts with explicit or filter-based discovery.
`get_fx_rates_and_conversion`	`fx`	FX rates, conversion, and historical rate series.
`get_payments_status`	`payment_status`	Structured payment search by UETR, reference, amount, value date, currency, or account.
`get_nio_hello`	`mock_data`	Connectivity/health check — returns a greeting with the current server time.

Tool: `get_accounts_balances`

Retrieves the account list or account balances for the authenticated HSBC customer. No arguments are required — calling with no params returns balances for all discoverable accounts.

Parameters

Name	Description
action string	Select account list or account balances endpoint. Default: balances. Allowed: list, balances
fields string	Comma-separated list of response fields to scope a list request. e.g. accountId,currency,accountName

Example request

{
  "action": "balances",
  "fields": "bic,iban,currentAvailableBalance,currentBookedBalance"
}

Tool: `get_account_transactions`

Retrieves transaction history for one or more accounts, with two discovery modes. Use explicit to supply known account IDs, or filter to let the tool discover accounts, optionally narrowed by currency.

Parameters

Name	Description
selection string	Account selection mode. Default: filter. Allowed: explicit, filter
accounts conditional array of object	Account list when selection=explicit. 1–30 objects: { accountId, accountName?, currency? }. Required if selection=explicit
currency string	Currency filter when selection=filter. Omit to consider all accounts. e.g. GBP, USD
maxAccounts integer	Max accounts queried for filter or multi-account requests. Default: 10. Max: 10
lookbackDays integer	Transaction lookback window, clamped to 365. Default: 7
limit integer	Page size — only for single explicit account queries. Clamped to 200. Default: 20
offset integer	Pagination offset — only for single explicit account queries. Default: 0
includeRawHSBCnetData boolean	Include raw HSBCnet fields — only for single explicit account queries. Default: false
allowPartial boolean	Return successful results even if some accounts fail. Default: true
confirmed boolean	Set true to proceed after confirming a broad unfiltered selection. Default: false

Notes

Pagination (limit, offset) and includeRawHSBCnetData are only available when querying exactly one explicit account.
Broad unfiltered filter selections may require an initial confirmation round-trip (confirmed: true) before execution.

Example: explicit account

{
  "selection": "explicit",
  "accounts": [
    {
      "accountId": "GBHBEUCA40051500105741",
      "currency": "GBP"
    }
  ],
  "lookbackDays": 7,
  "limit": 50
}

Example: filter by currency

{
  "selection": "filter",
  "currency": "GBP",
  "lookbackDays": 7,
  "maxAccounts": 5,
  "allowPartial": true
}

Tool: `get_fx_rates_and_conversion`

Multi-purpose FX tool covering live rates, conversion, and historical rate series. Behaviour is switched entirely by the action parameter.

Parameters

Name	Description
action string	FX operation to execute. Default: convert. Allowed: list-rates, convert, current-rate-by-pairs, history-by-range, currency-zone-history-by-range, history
values conditional array of object	Amounts to convert. Each: { currencyCode, amount }. Required for action=convert. amount is a numeric string, e.g. "100.50"
convertTo conditional string	Target currency for conversion. Required for action=convert. e.g. GBP, USD
ccyPairs conditional array of string	6-letter currency pairs. Tolerant of slashes, spaces, and lower case. Required for range/pair actions. e.g. ["USDCNY","CNYJPY"]
period conditional string	Time-range bucket. Required for history-by-range. Allowed: hour, day, oneday, oneweek, onemonth, threemonth, sixmonth, oneyear
mins string	Sampling interval in minutes. For history, must be 60–720. e.g. 60, 120, 720
fromCurrency conditional string	Source currency for action=history. e.g. USD
toCurrency conditional string	Target currency for action=history. e.g. GBP
days string	Lookback window for action=history. Max 3. Default: 3

Action guide

Action	Required params
`list-rates`	none
`convert`	`values`, `convertTo`
`current-rate-by-pairs`	`ccyPairs`
`history-by-range`	`ccyPairs`, `period`, `mins`
`currency-zone-history-by-range`	`ccyPairs`, `period`, `mins`
`history`	`fromCurrency`, `toCurrency`; optional `days`, `mins`

Example request

{
  "action": "convert",
  "convertTo": "GBP",
  "values": [
    {
      "currencyCode": "USD",
      "amount": "100"
    }
  ]
}

Tool: `get_payments_status`

Structured search over payment records — by UETR, reference, amount, value date, currency, or account.

Parameters

Name	Description
locale required string	Locale code forwarded to the downstream request header. e.g. en_GB, es_MX
searchCriteria required string \| object	At least one criterion required. Structured fields: uetr, e2eHsbcReference, debitAccountNumber, debitClientCin, crediteClientAccountNumber, amount, currency, valueDate / valueDateFrom / valueDateTo.
filterCurrency string \| string[]	Currency filter. e.g. USD, ["USD","GBP"]
filterStatus string \| string[]	Payment status filter. e.g. PENDING, ["PENDING","REJECTED"]
filterPaymentTypes string \| string[]	Payment type filter for summary results.
paymentType string	Single payment type filter.
instructionReference string	Payment instruction reference filter.
instructionCategory string	Instruction category. Default: single
offset integer	Zero-based pagination offset. Default: 0
rowCount integer	Max rows returned, capped at 100. Default: config value
sortBy string	Sort field. Default: valueDate
sortOrder string	Sort direction. Default: desc
includeCount boolean	Include total payment count for load-more style requests. Default: false

Example request

{
  "locale": "en_GB",
  "searchCriteria": {
    "uetr": "6fd0c4bc-3ce6-4f90-a4d7-8e4b31f1ac5d",
    "valueDateFrom": "2026-08-01",
    "valueDateTo": "2026-08-21",
    "currency": "USD"
  },
  "rowCount": 25,
  "offset": 0
}

Tool: `get_nio_hello`

Connectivity/health check. Takes no parameters and returns a greeting plus the current server time.

Example request

{}

Behavioural notes

Pagination caps are enforced server-side and silently clamped rather than erroring (e.g. get_account_transactions limit > 200 → 200; get_payments_status rowCount > 100 → 100).
Broad queries require confirmation: get_account_transactions with an unfiltered filter selection expects a confirmed: true follow-up before running against a large account set — build this as a two-step flow in any integration.
Tolerant currency-pair parsing: get_fx_rates_and_conversion ccyPairs accepts loosely formatted input (slashes, spaces, lower case) and normalises to strict 6-letter uppercase pairs.
Partial failure handling: multi-account transaction requests default to allowPartial: true, so a single failing account will not fail the whole call unless explicitly disabled.

MCP call examples

The MCP Server uses the standard JSON-RPC protocol. Below are raw examples of the session flow: initialize, list tools, then call a tool.

Initialize session

Start a new session. The response includes a mcp-session-id header that must be included in all subsequent requests.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "mcp-client",
      "version": "1.0.0"
    }
  }
}

List tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Call tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_accounts_balances",
    "arguments": {
      "action": "balances"
    }
  }
}

Key Information

Server details

Setup

Verify it works

Available tools

Service discovery

Tool: get_accounts_balances

Parameters

Example request

Tool: get_account_transactions

Parameters

Notes

Example: explicit account

Example: filter by currency

Tool: get_fx_rates_and_conversion

Parameters

Action guide

Example request

Tool: get_payments_status

Parameters

Example request

Tool: get_nio_hello

Example request

Behavioural notes

MCP call examples

Initialize session

List tools

Call tool

Tool: `get_accounts_balances`

Tool: `get_account_transactions`

Tool: `get_fx_rates_and_conversion`

Tool: `get_payments_status`

Tool: `get_nio_hello`