# AI integration quickstart

Calcgrid is a public, read-only calculator service. The shortest reliable agent flow is: discover, inspect the schema, calculate, then follow the response links.

## REST / OpenAPI

1. Discover the service: [status](https://tttkmbb.com/api/v1/status) or [OpenAPI](https://tttkmbb.com/openapi.json).
2. Search by natural-language keywords:

```http
GET https://tttkmbb.com/api/v1/search?query=mortgage
```

3. Read the selected schema, then calculate with its exact input names:

```http
GET https://tttkmbb.com/api/v1/calculators/mortgage-payment
GET https://tttkmbb.com/api/v1/calculate/mortgage-payment?home_price=400000&down_payment=80000&annual_rate_percent=6.5&term_years=30
```

For JSON-body clients, `POST /api/v1/calculate/{calculator_id}` with `{"inputs": {...}}` is also supported. Successful responses include the formula, units, sources, freshness, cache metadata and `next_actions`.

## MCP (Streamable HTTP)

Use this server configuration:

```json
{
  "mcpServers": {
    "calcgrid": {
      "type": "streamable-http",
      "url": "https://tttkmbb.com/mcp"
    }
  }
}
```

Recommended tool sequence: `search_calculators` → `get_calculator_schema` → `run_calculator` (or a typed `calculate_*` tool). All tools are read-only and complete synchronously.

## A2A

Read the [Agent Card](https://tttkmbb.com/.well-known/agent-card.json) and send JSON-RPC 2.0 to [`/a2a`](https://tttkmbb.com/a2a). A text message can be `search: mortgage` or `bmi weight_kg=70 height_cm=175`; a data part can send `{"calculator_id":"bmi","inputs":{"weight_kg":70,"height_cm":175}}`.

## Discovery compatibility

- [llms.txt](https://tttkmbb.com/llms.txt) — compact model-oriented overview
- [AI plugin manifest](https://tttkmbb.com/.well-known/ai-plugin.json) — legacy-compatible OpenAPI descriptor
- [ARD manifest](https://tttkmbb.com/.well-known/ard.json) — machine-readable catalog of REST, MCP, A2A and docs
- [MCP server card](https://tttkmbb.com/.well-known/mcp-server-card.json) — MCP directory metadata

No API key, cookies or user data are required. Respect the documented fair-use limit of 600 requests per minute per client IP and cache deterministic results when appropriate.