# Model Context Protocol (MCP)

Connect your AI assistant to the MCP Server to interact with accounts,
transactions, FX rates, and payment tracking — without writing a single line of code.

## 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.

### Claude Code

```bash
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:

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

### Cursor

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

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

### VS Code

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

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

### Other clients

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:

```json
{
  "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

| 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.

| Name | Type | Required | 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:

```json
{
  "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.

| Name | Type | Required | Description |
|---|---|---|---|
| `selection` | string | | Account selection mode. Default: filter. Allowed: explicit, filter |
| `accounts` | array of object | conditional | Account list when selection=explicit. 1–30 objects: { accountId, accountName?, currency? }. |
| `currency` | string | | Currency filter when selection=filter. Omit to consider all accounts. |
| `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:

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

Example — filter by currency:

```json
{
  "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.

| Name | Type | Required | 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` | array of object | conditional | Amounts to convert. Each: { currencyCode, amount }. Required for action=convert. |
| `convertTo` | string | conditional | Target currency for conversion. Required for action=convert. |
| `ccyPairs` | array of string | conditional | 6-letter currency pairs. Tolerant of slashes, spaces, and lower case. |
| `period` | string | conditional | 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. |
| `fromCurrency` | string | conditional | Source currency for action=history. |
| `toCurrency` | string | conditional | Target currency for action=history. |
| `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:

```json
{
  "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.

| Name | Type | Required | Description |
|---|---|---|---|
| `locale` | string | required | Locale code forwarded to the downstream request header. e.g. en_GB, es_MX |
| `searchCriteria` | string \| object | required | At least one criterion required. Structured fields: uetr, e2eHsbcReference, debitAccountNumber, debitClientCin, crediteClientAccountNumber, amount, currency, valueDate / valueDateFrom / valueDateTo. |
| `filterCurrency` | string \| string[] | | Currency filter. |
| `filterStatus` | string \| string[] | | Payment status filter. |
| `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. |
| `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:

```json
{
  "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.

```json
{}
```

## 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 — the response includes a `mcp-session-id` header that must be
included in all subsequent requests.

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

List tools:

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

Call tool:

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