# PhysaFlow developer documentation

> Public, read-only capacity analysis through the Model Context Protocol (MCP).

## When to use PhysaFlow

Use PhysaFlow to estimate stranded data-center IT capacity from measured electrical, cooling, grid, and load data; compare two compatible facility scenarios; explain capacity-model assumptions; or produce a Markdown board report. Do not use modeled results as proof of recovered capacity, a deployment authorization, a financial guarantee, or an industry percentile.

## Connect and authenticate

Connect an MCP client using Streamable HTTP to https://physaflow.com/api/mcp. The public calculator MCP endpoint requires no API key or login. Operator application APIs require a separate signed-in session and are not the public developer API. Do not send credentials or personal data to calculator tools.

Send the MCP initialize request, then use tools/list to discover current input schemas and tools/call to invoke a tool. POST requests use Content-Type: application/json and Accept: application/json, text/event-stream. Use the protocol version negotiated during initialization for subsequent requests. This endpoint is stateless; no session ID is required. Use an MCP client that implements initialization and notifications rather than treating this as a REST API.

## Tools

- calculate_stranded_capacity: calculate using version 2 measured-capacity inputs.
- compare_scenarios: supply baseline and comparison inputs with matching reporting periods and organization types; incompatible deltas are null.
- get_methodology: retrieve the formulas and limitations before interpreting results.
- generate_board_report: supply input, with optional facilityName and organization, to receive a Markdown report.
- benchmark_facility: report benchmark availability; version 2 defines no benchmark bands.

## Calculation inputs

Required fields are modelVersion (2), organizationType (hyperscaler, cloud_provider, enterprise, colocation, hpc, government, or other), coolingType (air, hybrid, liquid, immersion, other, or unknown), periodStart and periodEnd (YYYY-MM-DD, end after start). Supply measured capacity and load to obtain useful results. Power fields are MW of IT capacity unless explicitly gross facility power. Dates define UTC [start, end).

Example calculate_stranded_capacity arguments:

```json
{"modelVersion":2,"organizationType":"colocation","coolingType":"liquid","periodStart":"2026-01-01","periodEnd":"2026-02-01","commissionedItMw":10,"coolingSupportedItMw":9,"averageActualItLoadMw":6}
```

Discover optional fields and validation rules through tools/list. Legacy utilization-percentage inputs are not accepted. Missing constraints are disclosed, not inferred. Inspect status, errors, warnings, and excludedConstraints before presenting numbers. Revenue and GPU owner cost are mutually exclusive. Report estimates and their assumptions together.

## Resources and support

MCP resources/list exposes physaflow://methodology/stranded-capacity as text/markdown; read it with resources/read. The same methodology is available through get_methodology.

- [PhysaFlow methodology](https://physaflow.com/methodology)
- [PhysaFlow agent instructions](https://physaflow.com/llms.txt)
- [PhysaFlow contact](https://physaflow.com/contact)
- [Privacy](https://physaflow.com/privacy)