# AI Agents and Currency Tools

> Choose between the HTTP AI endpoint and MCP tools, and understand how each call is metered.

Canonical: https://currency-core.com/docs/guides/ai-agents/
Updated: 2026-11-12
Published: 2026-11-11

---
## The job

Give an agent the ability to answer currency questions or call currency tools. There are two surfaces, and they are not the same thing.

## Pick the surface

| Surface | Use it for | Transport |
|---|---|---|
| [`/v1/ai`](/docs/ai-endpoint/) | One natural-language question, answered with plain text plus structured `data` | HTTP only |
| [MCP](/docs/mcp/) | Let an agent choose and call individual currency tools | Remote Streamable HTTP |

The AI endpoint is HTTP only. The same currency tools are available over MCP, but `/v1/ai` itself is not an MCP tool.

## What MCP exposes

The MCP server has 14 tools. Two are public reference tools: `list_countries` and `list_currencies`. The keyed tools cover conversion, rates, history, PPP, and the seven analytics measures: `analyze_history`, `analyze_ppp`, `analyze_volatility`, `analyze_correlation`, `analyze_drawdown`, `analyze_safe_haven`, and `analyze_mean_reversion`. The analytics tools require Growth or higher, and the plan gate is enforced when the tool is called.

A successful keyed tool call is one API request. Public reference tools are unmetered, but they still require an authorized MCP connection.

```bash
curl "https://api.currency-core.com/v1/ai?q=Convert%2050%20USD%20to%20INR" \
  -H "Authorization: Bearer cc_live_your_key"
```

```json
{
  "query": "Convert 50 USD to INR",
  "answer": "50 USD is about 4,172.50 INR at the 2026-11-10 reference rate.",
  "data": [
    {
      "from": "USD",
      "to": "INR",
      "amount": 50,
      "result": 4172.5,
      "rate": 83.45,
      "pppApplied": false,
      "asOf": "2026-11-10"
    }
  ],
  "toolCalls": 1
}
```

The response has `query`, `answer`, `data`, `toolCalls`, and optionally `byok`. Treat `data` as canonical because the prose can misstate a figure. Each request is stateless, with no conversation memory and no streaming.

Native `/v1/ai` uses 1 AI credit per question. With BYOK, you use 1 API request per successful tool call and no credits. See [AI credits](/docs/ai-credits/).

A failed keyed tool call is not billed. `401` means the connection needs to be re-authorized, `403` means the plan lacks the tool, and `429` means the organization hit its monthly quota or per-minute limit. See [errors](/docs/errors/) and [MCP troubleshooting](/docs/mcp-troubleshooting/).

## Related docs

[AI endpoint](/docs/ai-endpoint/), [AI response schema](/docs/ai-response-schema/), [MCP tools](/docs/mcp-tools/), [MCP vs REST](/docs/mcp-vs-rest/), [AI credits](/docs/ai-credits/), and the [guides hub](/docs/guides/).