For agents and developers

BlueLux API & MCP

BlueLux provides public tools for pool chemistry, diagnostics, operating guidance, and Playbook search. BlueLux Operator is the professional platform we are building for pool operators, and the public calculation tools are grounded in the same deterministic chemistry work that supports our daily operation.

No authentication120 requests/minuteStructured JSONVersioned provenance

Connect your agent

Copy this sentence into an agent. The linked setup document explains BlueLux, MCP, REST, the available tools, safe use, and connection verification.

Fetch and follow the instructions to connect me to the BlueLux API and MCP from https://bluelux.com/agent-setup/prompt.md

Integration resources

Setup documentOne complete guide for people and agents Tool catalogCurrent tool names and input schemas OpenAPI 3.1REST contract for applications MCP manifestRemote server registration metadata DatasetsTargets, factors, bands, and decision trees

Live request

Try a tool

Choose a tool, edit the raw JSON request, and inspect the complete production response. No key is required.

Loading schemaPOST /api/v1/tools/calculate_pool_dose

ToolArguments (JSON)

Raw response

Run the example to see the complete JSON response.

REST API

REST is the simplest option for scripts, backends, workflows, and agents with an HTTP tool. Read the catalog, choose a tool, and send a JSON object to its endpoint.

The chlorine example omits product strength so the response shows the current default profile. You can instead send a named product_profile_id, or explicit product_strength_percent and product_density_g_ml values. Acid and soda ash require total alkalinity because their demand cannot be sized safely from pH alone.

Shell: dose request

curl https://bluelux.com/api/v1/tools/calculate_pool_dose \
  -H 'Content-Type: application/json' \
  --data '{
    "chemical": "liquid_chlorine",
    "volume_gallons": 10000,
    "current": 1,
    "target": 5
  }'

JavaScript example

JavaScript: LSI request

const response = await fetch(
  "https://bluelux.com/api/v1/tools/calculate_lsi",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      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"
    })
  }
);

const data = await response.json();

MCP

Connect a compatible MCP client to https://bluelux.com/mcp. The server is public and does not require caller authentication. The setup document above includes ready-to-use Codex, Claude Code, Cursor, and generic client configuration.

Direct MCP tools/list request

Shell: MCP tools/list

curl https://bluelux.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "my-agent",
          "version": "1.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Tool reference

Open a tool to inspect its live JSON Schema, required fields, accepted values, units, omission behavior, and a request body you can copy.

Loading catalog

calculate_pool_doseCalculate exact and practical amounts for a specified chemical correction.

Attribute	Requirement	Type or values	Definition
`chemical`	Required	liquid_chlorine \| muriatic_acid \| sodium_bicarbonate \| calcium_chloride \| cyanuric_acid \| pool_salt \| soda_ash	Chemical or product family to calculate.
`volume_gallons`US gallons	Required	integermin 100, max 2000000	Total water volume used to scale the calculation.
`current`pH or ppm	Required	numbermin 0, max 100000	Current measured value. For acid and soda ash this is pH; otherwise it is concentration.
`target`pH or ppm	Required	numbermin 0, max 100000	Desired value after the calculated correction.
`product_profile_id`	Optional	stringmin length 1, max length 100	A named product profile from the published profile dataset.If omitted: The disclosed default profile for the selected chemical is used.
`product_strength_percent`%	Optional	numbergreater than 0, max 100	Explicit active strength or purity override.If omitted: The resolved product profile supplies strength.
`product_density_g_ml`g/mL	Optional	numbergreater than 0, max 3	Liquid density override used when mass and volume conversion requires it.If omitted: The resolved product profile supplies or derives density when supported.
`total_alkalinity_ppm`ppm	OptionalRequired for muriatic acid and soda ash.	numbermin 0, max 1000	Measured total alkalinity as calcium carbonate.
`cyanuric_acid_ppm`ppm	Optional	numbermin 0, max 1000	Measured cyanuric acid used for chlorine context and carbonate alkalinity correction.If omitted: The tool follows its documented default or reduced-precision path.
`borates_ppm_as_boron`ppm as boron	Optional	numbermin 0, max 1000	Borate concentration expressed as elemental boron.If omitted: Treated as absent by the current calculation profile.
`free_chlorine_ppm`ppm	Optional	numbermin 0, max 100	Free chlorine used as an optional chemistry-model input.If omitted: Treated as absent when the selected model permits it.
`temperature_f`°F	Optional	numbermin 32, max 140	Water temperature.If omitted: The response discloses any default used.
`tds_ppm`ppm	Optional	numbergreater than 0, max 100000	Total dissolved solids.If omitted: The response discloses any default used.

POST /api/v1/tools/calculate_pool_dose

{
  "chemical": "liquid_chlorine",
  "volume_gallons": 10000,
  "current": 1,
  "target": 5
}

calculate_lsiCalculate LSI with the BlueLux continuous profile or the PHTA 2024 factor-table profile.

Attribute	Requirement	Type or values	Definition
`ph`pH	Required	numbermin 0, max 14	Measured water pH.
`total_alkalinity_ppm`ppm	RequiredRequired for muriatic acid and soda ash.	numbergreater than 0, max 1000	Measured total alkalinity as calcium carbonate.
`calcium_hardness_ppm`ppm	Required	numbergreater than 0, max 10000	Measured calcium hardness as calcium carbonate.
`temperature_f`°F	Optional	numbermin 32, max 140Default: 77	Water temperature.If omitted: The response discloses any default used.
`tds_ppm`ppm	Optional	numbergreater than 0, max 100000Default: 1000	Total dissolved solids.If omitted: The response discloses any default used.
`cyanuric_acid_ppm`ppm	Optional	numbermin 0, max 1000Default: 0	Measured cyanuric acid used for chlorine context and carbonate alkalinity correction.If omitted: The tool follows its documented default or reduced-precision path.
`calculation_profile`	Optional	bluelux_equilibrium_v1 \| phta_2024_table_v1Default: bluelux_equilibrium_v1	Versioned LSI calculation method.If omitted: The current BlueLux equilibrium profile is used.

POST /api/v1/tools/calculate_lsi

{
  "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"
}

get_metals_protocolReturn the diagnostic sequence for suspected metal staining or colored water.

Attribute	Requirement	Type or values	Definition
`symptom`	Optional	stringmax length 500	Plain-language observation used to focus the diagnostic protocol.If omitted: The response returns the general protocol.
`confirmed_metal`	Optional	iron \| copper \| manganese \| unknown	Metal identified by a reliable test, or unknown.If omitted: The metal is treated as unknown.

POST /api/v1/tools/get_metals_protocol

{
  "symptom": "rust-colored stains after chlorine was added",
  "confirmed_metal": "iron"
}

get_nutrient_thresholdsInterpret phosphate and nitrate readings as operating context rather than universal health limits.

Attribute	Requirement	Type or values	Definition
`phosphate_ppb`ppb	Optional	number	Measured orthophosphate result.If omitted: Phosphate-specific interpretation is omitted.
`nitrate_ppm`ppm	Optional	number	Measured nitrate result.If omitted: Nitrate-specific interpretation is omitted.

POST /api/v1/tools/get_nutrient_thresholds

{
  "phosphate_ppb": 500,
  "nitrate_ppm": 12
}

diagnose_filter_circulationReturn deterministic checks from pressure, flow, and pump-prime observations.

Attribute	Requirement	Type or values	Definition
`filter_pressure_psi`psi	Optional	number	Current operating filter pressure.If omitted: No numeric pressure comparison is produced.
`baseline_pressure_psi`psi	Optional	number	Clean-filter pressure for this equipment under comparable conditions.If omitted: No percentage change from baseline is produced.
`visible_flow`	Optional	normal \| low \| none \| surging	Observed return-flow condition.
`pump_primed`	Optional	boolean	Whether the pump has a stable water-filled prime.

POST /api/v1/tools/diagnose_filter_circulation

{
  "filter_pressure_psi": 22,
  "baseline_pressure_psi": 14,
  "visible_flow": "low",
  "pump_primed": true
}

get_seasonal_checklistReturn an ordered residential or public-facility checklist.

Attribute	Requirement	Type or values	Definition
`action`	Required	startup \| shutdown	Checklist direction.
`facility_type`	Optional	residential \| public	Residential or public-facility context.If omitted: Residential is used by the current tool.

POST /api/v1/tools/get_seasonal_checklist

{
  "action": "startup",
  "facility_type": "residential"
}

search_playbookReturn ranked Playbook passages with versions, sources, and canonical URLs.

Attribute	Requirement	Type or values	Definition
`query`	Required	stringmin length 2, max length 500	Natural-language Playbook search query.
`limit`	Optional	integermin 1, max 8	Maximum number of ranked passages to return.If omitted: The service applies its default result count.

POST /api/v1/tools/search_playbook

{
  "query": "free chlorine is low and pH is high",
  "limit": 3
}

Results and errors

Successful resultsThe tester shows the complete JSON response without translating or hiding fields. Common metadata includes source_page, confidence, rationale, and data_version. Dose results distinguish the complete mathematical correction from the practical field amount and any bounded current step.

ErrorsInvalid inputs return structured 4xx errors. If the calculation service is unavailable, the API returns an error instead of inventing a result.

The engine behind the API

Informed by BlueLux Operator

BlueLux Operator is the agent-first operating platform we are building for professional pool operators. The public API is a narrow, documented calculation surface and does not provide access to private customer data or operating workflows.

Learn about BlueLux Operator and register interest

Safety and operating scope

These tools provide calculations and operating guidance from the inputs supplied. Confirm pool volume, measurements, units, product concentration, and facility type. Follow the returned scope and sources. Product labels, Safety Data Sheets, manufacturer instructions, emergency directions, and controlling codes take precedence. Public aquatic facilities require facility-plan and jurisdiction review.