# Connect BlueLux to your agent

BlueLux is building a national pool and spa knowledge system for technicians, operators, software, and AI agents. The BlueLux API and MCP server expose deterministic chemistry calculations, operating guidance, diagnostics, datasets, and Playbook search through public, structured interfaces.

BlueLux Operator is the professional operating platform being built inside BlueLux. The public dosing and LSI tools are grounded in the same deterministic chemistry work that supports BlueLux's daily operation.

Use these instructions to connect an agent or application to BlueLux. No account or API key is required.

## What is available

Read the live tool catalog before relying on a fixed list. The current public tools include:

1. `calculate_pool_dose`
2. `calculate_lsi`
3. `get_metals_protocol`
4. `get_nutrient_thresholds`
5. `diagnose_filter_circulation`
6. `get_seasonal_checklist`
7. `search_playbook`

Every result includes a value, unit, source page, confidence, rationale, and data version. Calculation results also identify the engine revision used.

The dosing tool returns the exact full correction and a practical field amount. When a correction must be staged, it also returns the exact bounded step before field rounding. It discloses rounding direction, product assumptions, dose caps, projected chemistry, and whether the dose must be split and retested. Muriatic acid and soda ash require total alkalinity. Do not estimate TA from pH.

## Preferred connection: MCP

Register this public MCP endpoint as `bluelux`:

`https://bluelux.com/mcp`

### Codex

```sh
codex mcp add bluelux --url https://bluelux.com/mcp
```

### Claude Code

```sh
claude mcp add --transport http bluelux https://bluelux.com/mcp
```

### Cursor and other JSON-configured clients

```json
{
  "mcpServers": {
    "bluelux": {
      "url": "https://bluelux.com/mcp"
    }
  }
}
```

Reload the agent if it reads MCP configuration only at startup. Then list the available tools and confirm that the BlueLux catalog is available.

## REST connection

Use REST when the agent or application can make normal HTTP requests but cannot connect to MCP.

- Tool catalog: `GET https://bluelux.com/api/v1/tools`
- Tool call: `POST https://bluelux.com/api/v1/tools/:tool_name`
- OpenAPI: `GET https://bluelux.com/openapi.json`
- Content type: `application/json`
- Authentication: none

Send tool arguments directly as the JSON request body. Do not wrap them in an `arguments` property.

Example:

```sh
curl https://bluelux.com/api/v1/tools/calculate_lsi \
  -H 'Content-Type: application/json' \
  --data '{
    "ph": 7.8,
    "total_alkalinity_ppm": 100,
    "calcium_hardness_ppm": 400,
    "temperature_f": 80,
    "tds_ppm": 3200,
    "cyanuric_acid_ppm": 50,
    "calculation_profile": "bluelux_equilibrium_v1"
  }'
```

## How to use BlueLux results

1. Read the live tool catalog before calling a tool.
2. Use the narrowest tool that fits the question.
3. Preserve the source page, confidence, rationale, data version, and calculation provenance in downstream answers or records.
4. Do not invent missing measurements or substitute an unverified local calculation.
5. Confirm volume, units, product concentration, facility type, and safety constraints before recommending an action.
6. Treat results as decision support. Product labels, Safety Data Sheets, manufacturer instructions, emergency directions, and controlling laws or codes take precedence.

## Products, defaults, and overrides

The live product profiles are available at `https://bluelux.com/datasets/v1/product-profiles.json`.

For dosing, use this order:

1. Send `product_profile_id` when the exact listed product is known.
2. Otherwise send explicit `product_strength_percent` and, for liquid acid, `product_density_g_ml` when known from the label or Safety Data Sheet.
3. Otherwise omit those fields and inspect `product_resolution` in the result to see the published generic default that was used.

Never hide an override. Preserve `product_resolution`, `exact_amount`, `exact_step_amount` when present, `field_amount`, rounding, limits, and projected chemistry in downstream records. `exact_amount` is the complete mathematical correction. `exact_step_amount` is the permitted current step before field rounding. `field_amount` is the practical amount to apply now.

## LSI profiles

`calculate_lsi` accepts two calculation profiles:

- `bluelux_equilibrium_v1` uses the continuous BlueLux calculation and pH-aware carbonate alkalinity correction.
- `phta_2024_table_v1` reproduces the PHTA 2024 factor-table method, including its next-greatest-factor rule and its published balance band.

Use the BlueLux profile by default. Use the PHTA profile when teaching, auditing, or reproducing a PHTA example. Always retain the returned profile name.

## Reusing pool-specific measurements

Freshness policies are published at `https://bluelux.com/datasets/v1/measurement-freshness.json`. A stored result may be reused only for one of its listed purposes, within its applicable age window, and only when no later event invalidated it. Never infer sulfate, chloride, silica, iron, copper, or another constituent from TDS or postal code.

## Verify the connection

Call `calculate_lsi` with the example above. Confirm that the response includes:

- a structured LSI result;
- `source_page`;
- `confidence`;
- `rationale`;
- `data_version`;
- calculation provenance.

When setup is complete, tell the user which connection method you used, where its configuration lives, which tools were discovered, and whether the verification call succeeded.

## Machine references

- Human documentation and live tester: `https://bluelux.com/developers/agents`
- Tool catalog: `https://bluelux.com/api/v1/tools`
- OpenAPI 3.1: `https://bluelux.com/openapi.json`
- MCP manifest: `https://bluelux.com/mcp-server.json`
- Dataset index: `https://bluelux.com/datasets/v1/index.json`
- Product profiles: `https://bluelux.com/datasets/v1/product-profiles.json`
- Measurement freshness: `https://bluelux.com/datasets/v1/measurement-freshness.json`
- Playbook manifest: `https://bluelux.com/playbook/index.json`
- Playbook corpus: `https://bluelux.com/playbook/llms-full.txt`