MCP server

The PoolCloud MCP server lets AI assistants calculate pool chemical dosing directly, using the same formula engine that powers the REST API. It's hosted at api.poolcloud.com/mcp — no local installation required.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Instead of writing API calls yourself, the assistant talks to the PoolCloud server directly.

That means you can ask Claude (or any MCP-compatible assistant) "my pool's free chlorine is 0 and pH is 7.2, what should I add?" and it will run the actual PoolCloud formula engine to give precise dosing recommendations.

Setup

claude mcp add --transport http poolcloud https://api.poolcloud.com/mcp

No local installation, Node.js, or npm required. The MCP server is hosted alongside the PoolCloud REST API.

Available tools

`calculate`

Calculate pool chemical dosing recommendations from current water readings. Note that the MCP tool takes the pool fields flattened (pool_gallons, pool_water_type, pool_wall_type), unlike the REST endpoint's nested pool object.

Parameter	Type	Required	Description
`formula_id`	enum	Yes	`chlorine_cal_hypo`, `salt`, `bromine`, or `minerals`
`readings`	object	Yes	Current water readings as `{reading_id: value}` (e.g. `{fc: 2.5, ph: 7.2}`)
`pool_gallons`	number	Yes	Pool volume in US gallons
`pool_water_type`	enum	No	`chlorine`, `salt_water`, `bromine`, `minerals`, `copper`, `ozone`, `uv`
`pool_wall_type`	enum	No	`vinyl`, `plaster`, `fiberglass`, `concrete`, `pebble`
`target_levels`	array	No	Override default target ranges: `[{id, min, max}]`
`substitutions`	object	No	Override default treatments: `{reading_id: {up?, down?}}`

The tool returns human-readable step-by-step instructions along with the raw JSON.

Available resources

Reference data the assistant can browse without making tool calls:

URI	Description
`poolcloud://formulas`	The four formula IDs with names and descriptions
`poolcloud://readings`	Reading IDs with names, units, and default target ranges
`poolcloud://treatments`	Treatment IDs with names, types, and application instructions
`poolcloud://integration-guide`	REST API integration guide with code examples

Prompts

`analyze-pool-water`

A guided conversation template that walks through:

Pool type (chlorine, salt, bromine, minerals)
Pool size and wall material
Collecting water test readings
Running the calculation
Presenting results

Usage: ask your assistant to "analyze my pool water" or select the analyze-pool-water prompt. Optional parameter pool_type skips the first question.

Example conversations

Basic chlorine pool

You: My 15,000 gallon chlorine pool has FC=0, pH=7.8, TA=60, CYA=10. What chemicals do I need?

The assistant calls calculate with formula_id: "chlorine_cal_hypo" and your readings, then returns step-by-step dosing instructions.

Salt water pool

You: I have a 20,000 gallon salt water pool. Salt is at 2400 ppm, FC=1, pH=7.6. Help me balance it.

The assistant uses formula_id: "salt" and includes the salt reading.

With substitutions

You: Calculate chemicals for my pool (10,000 gal, FC=2, pH=7.0) but I want to use dichlor instead of cal-hypo for chlorine, and dry acid instead of muriatic acid for pH.

The assistant passes substitutions: {fc: {up: "dichlor"}, ph: {down: "sodium_bisulfate"}}.

Architecture

The MCP server runs alongside the REST API in the same process on api.poolcloud.com. Both drive the same formula engine:

AI assistant → MCP (streamable HTTP) → FastMCP → formula engine
Your app     → REST (/api/calculate/) → Django  → formula engine

The MCP server is a FastMCP ASGI app mounted at /mcp; Django handles every other route.

Troubleshooting

Server not appearing in Claude

Claude Desktop: make sure you entered the full URL https://api.poolcloud.com/mcp in Settings → Connectors.
Claude Code: run claude mcp list to verify the server is registered. Try removing and re-adding it.

Calculation errors

Verify formula_id is one of chlorine_cal_hypo, salt, bromine, minerals.
Ensure readings uses valid reading IDs (see the poolcloud://readings resource or the reading IDs table).
Check that pool_gallons is a positive number.