MCP Server (AI Integration)

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 (opens in a new tab) (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Instead of writing API calls yourself, the AI communicates directly with the PoolCloud server.

This means you can ask Claude (or any MCP-compatible assistant) questions like "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 you 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 based on current water readings.

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 raw JSON data.

Available Resources

These provide reference data that AI assistants can browse without making tool calls:

URI	Description
`poolcloud://formulas`	All 4 formula IDs with names and descriptions
`poolcloud://readings`	All 11 reading IDs with names, units, and default target ranges
`poolcloud://treatments`	All 22 treatment IDs with names, types, and application instructions
`poolcloud://integration-guide`	Complete 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 AI assistant to "analyze my pool water" or select the analyze-pool-water prompt.

Optional parameter: pool_type — skip the first question if you already know your pool type.

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 AI will call calculate with formula_id: "chlorine_cal_hypo" and your readings, then return 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 AI will use formula_id: "salt" and include 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 AI will pass 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 use the same Node.js formula engine via subprocess:

AI Assistant → MCP (streamable HTTP) → FastMCP → subprocess → formula engine
Web Client  → REST API (/api/calculate/) → Django → subprocess → formula engine

Single deployment, same Render service. The MCP server is a FastMCP (opens in a new tab) ASGI app mounted at /mcp, while Django handles all other routes.

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 the formula_id is one of: chlorine_cal_hypo, salt, bromine, minerals
Ensure readings uses valid reading IDs (see the poolcloud://readings resource)
Check that pool_gallons is a positive number

How Formulas Work