AI Integration

You can use Rates API in AI products without a private integration. The API gives documentation that machines can read, JSON responses with a fixed shape, an MCP endpoint, and a plain-text list of the documentation pages.

Use this page when you add Rates API to an AI product. Examples are chat assistants, research agents, search systems, workflows, and applications that call tools.

Integration Items

Item	URL	Use
MCP endpoint	POST /api/v1/mcp	Agents that use the Model Context Protocol (MCP)
Scalar OpenAPI reference	/openapi	Find endpoints and send test requests from the browser
OpenAPI JSON	/openapi/json	Make SDKs and agent tools, and check the contract
Documentation list for LLMs	/llms.txt	A plain-text list of the documentation pages, with titles and links
Full documentation for LLMs	/llms-full.txt	The full text of all documentation pages in one Markdown file
Search API	/api/search	Search in this documentation site

Recommended Architecture

Step	Component	Function
1	User question	A person asks for the newest rates, earlier rates, or a comparison.
2	AI assistant or workflow	The agent finds which data is necessary: documentation, endpoint data, or rates.
3	/llms.txt and /openapi/json	The agent finds the endpoints, the parameters, and the response shapes.
4	POST /api/v1/mcp	An MCP agent finds the Rates API tools and uses them.
5	/api/v1/* JSON endpoints	Direct tools and the MCP tools get the rates.
6	Answer	The agent gives an answer that uses API data and IDs.

Use OpenAPI and llms.txt to tell the agent which items are available. Use MCP if your agent runtime can find tools and call them. Send direct /api/v1/* requests if you make tools or a typed client.

MCP Endpoint

The MCP endpoint is at this URL:

POST https://www.ratesapi.nz/api/v1/mcp

The endpoint uses the Streamable HTTP transport and JSON-RPC 2.0. It accepts only POST requests. A GET or DELETE request gets HTTP 405.

Protocol Versions

Version	Type	How a client uses it
2026-07-28	Current	Each request contains its protocol version. An initialize request is not necessary.
2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05	Legacy	The client sends initialize first. If the server supports the requested version, it uses that version. If not, it uses 2025-11-25.

To get the list of supported versions, send server/discover. If you send a version that the server does not support, the server returns HTTP 400 and error -32022. The error data contains the list of supported versions.

The server does not use sessions. It does not send an Mcp-Session-Id header.

Connect a Client

The MCP server does not use an API key or OAuth. Give the endpoint URL to your MCP client.

Claude Code

Run this command:

claude mcp add --transport http ratesapi https://www.ratesapi.nz/api/v1/mcp

To share the server with your team, add it to the .mcp.json file at the root of your project:

{
  "mcpServers": {
    "ratesapi": {
      "type": "http",
      "url": "https://www.ratesapi.nz/api/v1/mcp"
    }
  }
}

Claude and Claude Desktop

Add Rates API as a custom connector:

1. Go to Customize > Connectors.
2. Select +, then select Add custom connector.
3. Type https://www.ratesapi.nz/api/v1/mcp as the remote MCP server URL. Then select Add.

Claude Desktop does not read remote servers from claude_desktop_config.json. Use a custom connector.

Cursor

Add the server to .cursor/mcp.json in your project. To use it in all projects, add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ratesapi": {
      "url": "https://www.ratesapi.nz/api/v1/mcp"
    }
  }
}

Requests for 2026-07-28

Each request must contain these items:

• In params._meta, the io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities fields
• The MCP-Protocol-Version header, with the same version as _meta
• The Mcp-Method header, with the same value as method
• For tools/call, the Mcp-Name header, with the same value as params.name

If a header is missing or does not match the body, the server returns HTTP 400 and error -32020. If a _meta field is missing, the server returns HTTP 400 and error -32602.

Method	Function
server/discover	Gives the supported versions, the capabilities, the server information, and instructions for LLMs
tools/list	Gives the list of Rates API tools and their input schemas
tools/call	Uses one tool with the arguments that you send

Each result contains resultType: "complete" and the server information in _meta. The results of server/discover and tools/list also contain ttlMs and cacheScope. A client can keep these results for one hour.

An unknown method gets HTTP 404 and error -32601. The ping method does not exist in 2026-07-28.

Legacy Requests

A legacy client sends initialize, then tools/list and tools/call. The server also accepts ping.

Clients for 2025-06-18 and later send the MCP-Protocol-Version header with the negotiated version. The server uses a request without this header as a 2025-03-26 request. Such a request can also be a JSON-RPC batch.

A notification (a message without an id) gets HTTP 202 with no body.

Tools

Category	Tools
Mortgages	list_mortgage_rates, get_mortgage_rates_by_institution, get_mortgage_rates_time_series
Personal loans	list_personal_loan_rates, get_personal_loan_rates_by_institution, get_personal_loan_rates_time_series
Car loans	list_car_loan_rates, get_car_loan_rates_by_institution, get_car_loan_rates_time_series
Credit cards	list_credit_card_rates, get_credit_card_rates_by_issuer, get_credit_card_rates_time_series

Each tool has a title and the readOnlyHint: true annotation. The tools only read data.

All tool arguments are strings. For example, send "termInMonths": "12", not "termInMonths": 12.

Example Tool Call

curl https://www.ratesapi.nz/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: list_mortgage_rates' \
  -d '{
    "jsonrpc": "2.0",
    "id": "rates-1",
    "method": "tools/call",
    "params": {
      "name": "list_mortgage_rates",
      "arguments": { "termInMonths": "12" },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

The result contains one text item. The text is the same JSON that the related REST endpoint returns. For 2025-06-18 and later, structuredContent also contains this JSON.

If the tool fails, the result contains isError: true. For 2025-11-25 and later, an incorrect argument also gives a result with isError: true. The model can then read the error and correct the argument.

Errors

Code	Message	Cause
-32700	Parse error	The request body is not JSON. The HTTP status is 400.
-32600	Invalid Request	The body is not a JSON-RPC 2.0 request.
-32601	Method not found	The method does not exist. For versions before 2025-11-25, an unknown tool also gives this error, with the message Tool not found.
-32602	Invalid params	A _meta field is missing, or the tool does not exist. For versions before 2025-11-25, an incorrect argument also gives this error.
-32603	Internal error	An error occurred on the server.
-32020	Header mismatch	A necessary header is missing, or it does not match the body. The HTTP status is 400.
-32022	Unsupported protocol version	The server does not support the version. The HTTP status is 400.

The MCP server sends listChanged: false, because the list of tools does not change while the API version stays the same. The rate data can change each hour.

OpenAPI for Tool Generation

Use /openapi/json if your AI framework can change OpenAPI operations into tools.

The OpenAPI document contains the /api/v1/* data endpoints and the MCP endpoint, POST /api/v1/mcp. The MCP operation (sendMcpMessage) shows the headers, the JSON-RPC message schemas, and the tool names. This page gives all the MCP information.

If your framework makes a tool from each OpenAPI operation, do not make a tool from sendMcpMessage. To use MCP, connect an MCP client to the MCP endpoint.

Documentation List for LLMs

Use /llms.txt when an assistant, a coding agent, or a search system must have a short plain-text list of the documentation.

/llms.txt shows each documentation page as a Markdown link, with its title and description. It also shows the OpenAPI document, the MCP endpoint, and the data endpoints. It does not contain the full text of the pages. To read a page, get the linked page. For request schemas and response schemas, use /openapi/json.

To get the full text of all pages in one file, use /llms-full.txt.

Use /llms.txt for these tasks:

• Add a list of the Rates API pages to the system prompt of an assistant.
• Let a search system find the available pages before it gets the necessary pages.
• Give a coding agent a list of pages to read.
• Keep the documentation separate from the rate data.

API Rules That Help Agents

Rule	Result
An API key is not necessary	Agents can make prototypes and tests without secrets.
The IDs of institutions and issuers do not change	The next tool call can use the same IDs.
JSON responses have a fixed shape	Tool results are easy to parse, check, and show.
Errors have a fixed shape	An agent can process incorrect tool arguments in the same way each time.
REST responses have an x-request-id header	You can connect agent logs to API logs.
Time-series filters	Agents can answer questions about earlier rates and trends.

Example Agent Tasks

• Compare the newest 12-month mortgage rates of New Zealand lenders.
• Find the newest rates of one institution before you write a reply to a customer.
• Make a daily summary when a monitored rate changes.
• Answer questions about earlier rates, for example, "What did ANZ offer last month?"
• Add the newest lending rates to a workflow for financial plans.

Select an Integration Path

If you make this	Start with
An MCP agent	POST /api/v1/mcp
An SDK or a typed client	/openapi/json
A chat assistant that reads docs	/llms.txt
A prototype in the browser	/openapi
A product feature	/api/v1/* endpoints