# AI agents & MCP Source: DepositScout Data API docs — https://depositscout.com/developers/ai-agents Connect Claude, Cursor and other AI agents to DepositScout's UK savings data. --- ## Overview - **MCP server** at `https://depositscout.com/api/mcp`: every Data API endpoint as a tool, for Claude, Cursor or any MCP client. It uses your API key and costs exactly what the REST API costs. - **WebMCP**: agents running in a visitor's browser get a few free, read-only tools that show a short sample of our pages. - **For crawlers and assistants**: `/llms.txt`, Markdown versions of every page, an API catalog and agent skills. See [discovery files](https://depositscout.com/developers/ai-agents#discovery). ## MCP server The server speaks MCP over Streamable HTTP at `https://depositscout.com/api/mcp`. It's stateless, so any MCP client that supports remote HTTP servers can connect. Send your API key as a header: `ds_test_…` for free sample data, `ds_live_…` for real data. Listing tools needs no key. Every tool call goes through the same gateway as the REST API: the same scopes, plans, rate limits, IP allow-list, credits and usage log. A live key is charged exactly as the matching endpoint is, so lists cost per row returned and a small `limit` keeps the cost down. Calls made through MCP show on your Usage page like any other request. A tool returns the endpoint's normal response, `{ data, meta }` with `meta.creditsCharged` and `meta.creditsBalance`, as both text and structured content, plus a `disclaimer` field (information, not financial advice) that your agent should pass on. An API error (no key, not enough credits, wrong plan) comes back as a tool error with the usual error body, and isn't charged. Start with the free `ping` and `me` tools to check the key, your balance and which tools it can call. ## Connect a client **Claude Code** ```claudecode claude mcp add --transport http depositscout https://depositscout.com/api/mcp \ --header "Authorization: Bearer ds_test_YOUR_KEY" ``` **Claude Desktop, Cursor and others (mcp.json)** ```json { "mcpServers": { "depositscout": { "url": "https://depositscout.com/api/mcp", "headers": { "Authorization": "Bearer ds_test_YOUR_KEY" } } } } ``` **curl** ```bash curl https://depositscout.com/api/mcp \ -H "Authorization: Bearer ds_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rates","arguments":{"type":"easy-access","limit":3}}}' ``` Cursor reads `.cursor/mcp.json`; Claude Desktop and most other clients take the same `url` and `headers`. The server card is at `/.well-known/mcp/server-card.json`. ## Tools One tool per endpoint. A tool's inputs are its endpoint's parameters, and the endpoint's docs page has the details. Send your key with `tools/list` and you get only the tools that key can call (its scopes, plan and mode), so an agent never picks one it would be refused on. Every tool's `_meta` has its price in machine-readable form, `"com.depositscout/cost": { "credits": 1, "unit": "row" }`, for showing or budgeting spend. | Tool | What it returns | Credits | | --- | --- | --- | | ping | [Check your key works](https://depositscout.com/developers/docs/ping) | Free | | me | [Your account, balance and limits](https://depositscout.com/developers/docs/me) | Free | | reference_providers | [Provider lookup](https://depositscout.com/developers/docs/reference.providers) | 1 | | reference_products | [Product lookup](https://depositscout.com/developers/docs/reference.products) | 1 | | reference_cards | [Card lookup](https://depositscout.com/developers/docs/reference.cards) | 1 | | reference_currencies | [Currency lookup](https://depositscout.com/developers/docs/reference.currencies) | 1 | | reference_account_types | [Account type lookup](https://depositscout.com/developers/docs/reference.account-types) | 1 | | reference_fscs | [FSCS banking licences](https://depositscout.com/developers/docs/reference.fscs) | 1 | | rates | [Live UK savings rates](https://depositscout.com/developers/docs/rates) | 1 / row | | rates_item | [One savings product](https://depositscout.com/developers/docs/rates.item) | 1 | | rates_link | [A product's page on the provider's site](https://depositscout.com/developers/docs/rates.link) | 1 | | history | [Rate change history](https://depositscout.com/developers/docs/history) | 2 / row | | history_components | [Base and bonus rate history](https://depositscout.com/developers/docs/history.components) | 2 / row | | rate_trends | [Market rate trends](https://depositscout.com/developers/docs/rate-trends) | 5 | | providers | [Provider directory](https://depositscout.com/developers/docs/providers) | 1 / row | | providers_item | [One provider](https://depositscout.com/developers/docs/providers.item) | 1 / row | | providers_service_quality | [Provider service quality](https://depositscout.com/developers/docs/providers.service-quality) | 2 | | switch_offers | [Current account switch offers](https://depositscout.com/developers/docs/switch-offers) | 1 / row | | account_offers | [Current account offers](https://depositscout.com/developers/docs/account-offers) | 2 / row | | cards_rewards | [Reward credit cards](https://depositscout.com/developers/docs/cards.rewards) | 2 / row | | cards_travel | [Travel cards](https://depositscout.com/developers/docs/cards.travel) | 2 / row | | cards_travel_fx_history | [FX rate history](https://depositscout.com/developers/docs/cards.travel.fx-history) | 5 | | fx_rates | [Latest exchange rates](https://depositscout.com/developers/docs/fx.rates) | 1 | | market_overview | [Market overview](https://depositscout.com/developers/docs/market.overview) | 5 | | market_averages | [Average rates](https://depositscout.com/developers/docs/market.averages) | 5 | | market_category_stats | [Category statistics](https://depositscout.com/developers/docs/market.category-stats) | 5 | | market_card_stats | [Card market statistics](https://depositscout.com/developers/docs/market.card-stats) | 5 | | market_hero_stats | [Headline statistics](https://depositscout.com/developers/docs/market.hero-stats) | 5 | | market_boe_rate | [Bank of England base rate](https://depositscout.com/developers/docs/market.boe-rate) | 5 | | market_ecb_rate | [ECB rate](https://depositscout.com/developers/docs/market.ecb-rate) | 5 | | market_inflation | [UK inflation](https://depositscout.com/developers/docs/market.inflation) | 5 | | simulate | [Simulate savings returns](https://depositscout.com/developers/docs/simulate) | 2 | | calculators_savings_tax | [Savings tax calculator](https://depositscout.com/developers/docs/calculators.savings-tax) | 1 | | calculators_isa_allowance | [ISA allowance calculator](https://depositscout.com/developers/docs/calculators.isa-allowance) | 1 | | calculators_savings_growth | [Savings growth calculator](https://depositscout.com/developers/docs/calculators.savings-growth) | 1 | | calculators_regular_saver | [Regular saver calculator](https://depositscout.com/developers/docs/calculators.regular-saver) | 1 | | assets_providers | [A provider's logo](https://depositscout.com/developers/docs/assets.providers) | 5 | | assets_cards | [A card's image](https://depositscout.com/developers/docs/assets.cards) | 5 | ## Prompts Ready-made workflows your MCP client can offer its user. A prompt is only a recipe, so it's free; the tool calls it leads to are charged as usual. Each one tells the model to explain with the tools' own facts (`matchReasons` and the simulation's `assumptions`), keep lists small, and say it isn't financial advice. - `compare_savings` (type, amount): Search, compare and simulate the top accounts of one type for a balance. - `check_savings_rate` (sourceKey, amount): Look up one account, simulate it (with and without a rate cut) and see how it compares. - `explain_rate_history` (sourceKey): Lay out how one account's rate has changed, with dates, without speculating why. ## Resources Free context an agent can read to explain the numbers, with no key and no credits: `depositscout://glossary` (account types and terms), `depositscout://disclaimer`, the Data Licence, FSCS protection, how we rank accounts, the guides index, and any guide through the `https://depositscout.com/guides/{slug}` template. Pages come back as Markdown, with rate tables shortened like the Markdown pages. The prompts' `type` and `sourceKey` arguments support completion, so a client can offer real values instead of guesses. ## Build an agent Connect with the official MCP SDK, give your model the tool list, and run the tool calls it asks for. Two tools help an agent answer without guessing: every `rates` item carries `matchReasons` (why it's in the result, as facts), and `simulate` works out what a balance would earn, including an intro bonus ending or a rate change. **TypeScript** ```typescript // npm install @modelcontextprotocol/sdk import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "my-savings-agent", version: "1.0.0" }); await client.connect( new StreamableHTTPClientTransport(new URL("https://depositscout.com/api/mcp"), { requestInit: { headers: { Authorization: `Bearer ${process.env.DS_API_KEY}` } }, }), ); // Hand these to your model as tools; run the calls it asks for. const { tools } = await client.listTools(); const rates = await client.callTool({ name: "rates", arguments: { type: "easy-access", amount: 50000, limit: 3 } }); const top = (rates.structuredContent as { data: any[] }).data[0]; const sim = await client.callTool({ name: "simulate", arguments: { sourceKey: top.sourceKey, amount: 50000 } }); console.log(top.accountName, top.matchReasons, (sim.structuredContent as { data: any }).data.result); // Or start from a ready-made workflow. const prompt = await client.getPrompt({ name: "compare_savings", arguments: { type: "cash-isa", amount: "20000" } }); await client.close(); ``` **Python** ```python # pip install mcp (Python 3.10+, MCP SDK 2.x) import asyncio, os import httpx2 from mcp import Client from mcp.client.streamable_http import streamable_http_client async def main(): headers = {"Authorization": f"Bearer {os.environ['DS_API_KEY']}"} async with httpx2.AsyncClient(headers=headers, timeout=30) as http: async with Client(streamable_http_client("https://depositscout.com/api/mcp", http_client=http)) as client: tools = await client.list_tools() # hand these to your model rates = await client.call_tool("rates", {"type": "easy-access", "amount": 50000, "limit": 3}) top = rates.structured_content["data"][0] sim = await client.call_tool("simulate", {"sourceKey": top["sourceKey"], "amount": 50000}) print(top["accountName"], top["matchReasons"], sim.structured_content["data"]["result"]) asyncio.run(main()) ``` Use a `ds_test_…` key while you build: every tool returns sample data for free, in the same shape as live data. ## WebMCP When an AI agent runs inside a visitor's browser (for example Chrome with WebMCP), every depositscout.com page offers it these read-only tools: - `find_savings_rates`: the top rates for one account type (easy-access, fixed-rate, notice, cash-isa and more) - `look_up_bank`: one bank or building society's best rates, accounts and switch offers - `list_switch_offers`: current account switching bonuses - `read_page`: any public page, such as `/guides` or `/fscs-protection` They're free and need no key, and they return the same shortened Markdown as the pages: each table and list is cut to its first 3 rows, with a link to the full page. For complete, structured data, use the MCP server or the REST API. ## Discovery files - `/llms.txt`: what DepositScout is and its main pages - Any page with `Accept: text/markdown`: that page as Markdown (tables shortened, as above) - `/.well-known/api-catalog`: the API's OpenAPI, docs and status (RFC 9727) - `/.well-known/mcp/server-card.json`: this MCP server - `/.well-known/agent-skills/index.json`: skills for reading the site and calling the API - `/.well-known/ai-catalog.json`: all of the above in one manifest - Every page sends a `Link` header pointing at these. ## Using the content Search engines and AI assistants are welcome to read our pages and cite them in answers; please link to the page. We don't allow our content to be used to train AI models (`Content-Signal: ai-train=no` in robots.txt). Data from the API and the MCP server is covered by the [Data Licence](https://depositscout.com/developers/licence).