> For the complete documentation index, see [llms.txt](https://calctree.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://calctree.gitbook.io/docs/integrations/ai-assistants.md).

# AI Assistants

Use your CalcTree calculations as tools inside AI assistants like Claude, ChatGPT, Gemini, Cursor, and others. The CalcTree AI skill teaches any large language model how to discover, execute, and build CalcTree calculation pages through the GraphQL API.

### What it does

Once installed, your AI assistant can:

* **Discover** — list the calculation pages in your workspace and see what's available
* **Execute** — run any page with custom inputs and read back results with real physical units (e.g. "run the beam calculator with a span of 12 m and a load of 30 kN/m")
* **Build** — create new calculation pages from scratch, complete with formulas, datasets, traffic lights, and cross-page references

Calculations run server-side on CalcTree's engine. The AI reads the results — it doesn't compute them itself, so the numbers are always exact.

### Supported AI tools

| Tool                                             | How it works                                                                                          |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Claude** (claude.ai, desktop app, Claude Code) | Install the skill pack (see below). Claude gets full read and write access to your workspace          |
| **ChatGPT / Gemini / other chat LLMs**           | Paste the skill document as a system prompt or file attachment, then provide your API key in the chat |
| **Cursor / Windsurf / Codex**                    | Point the tool at the AGENTS.md file in the calctree-skills repo                                      |

### Setup

You need two things: an API key and the skill itself.

#### 1. Generate an API key

Go to your workspace settings in CalcTree and generate an API key. This single key covers all operations — reading pages, executing calculations, creating new pages, and uploading datasets. When chatting with the AI, you can paste any CalcTree URL and it will identify your workspace and pages automatically.

See [Generating an API key](https://calctree.gitbook.io/docs/integrations/graphql-api/generating-an-api-key) for detailed steps.

#### 2. Install the skill

**Claude (claude.ai or desktop app):**

1. Download the skill pack: [calctree.zip](https://github.com/calctree/calctree-skills/releases/latest/download/calctree.zip)
2. Go to **Settings > Features > Skills** and upload the zip
3. Enable **Allow network** in Settings > Features (the skill needs to reach `graph.calctree.com`)
4. Start a new conversation and paste your API key: "My CalcTree API key is ..."

**Claude Code (CLI):**

```bash
export CALCTREE_API_KEY=your_key_here
```

The skill is available via the plugin marketplace, or copy the `skills/calctree/` folder into `~/.claude/skills/`.

**ChatGPT, Gemini, or other LLMs:**

1. Download [SKILL.md](https://raw.githubusercontent.com/calctree/calctree-skills/main/skills/calctree/SKILL.md) and attach it to your conversation (or paste it as a system prompt)
2. Include your API key in the message

For models with code execution (ChatGPT Code Interpreter, Gemini), also attach [calctree\_api.py](https://raw.githubusercontent.com/calctree/calctree-skills/main/skills/calctree/scripts/calctree_api.py) so they can run it directly.

For models without code execution, the skill includes the raw GraphQL queries they need to make HTTP calls.

**Cursor, Windsurf, Codex:**

These tools look for an `AGENTS.md` file. Point them at the [calctree-skills repository](https://github.com/calctree/calctree-skills) and they'll follow the instructions automatically.

### Example prompts

Once set up, try these:

| Prompt                                                                 | What happens                                                                                  |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| "List the pages in my workspace"                                       | Discovers all calculation pages and shows their names and IDs                                 |
| "Look at page X and tell me what inputs it takes"                      | Reads the page's variables, identifies inputs vs outputs, and shows current values with units |
| "Run the beam calculator with span = 12 m and load = 30 kN/m"          | Executes the calculation server-side and returns the results (e.g. M\_max = 540 kN\*m)        |
| "Run this for three cases and compare results"                         | Makes multiple execution calls and presents a comparison table                                |
| "Create a page that calculates deflection for a simply supported beam" | Builds a new page with formulas, registers it in your workspace, and returns the URL          |

### How it works under the hood

The skill wraps CalcTree's GraphQL API. It uses:

* The **pages** query to discover what's in a workspace
* The **calculation** query to read a page's variables and values
* **simpleCalculate** to execute a page with input overrides (read-only — doesn't change the page)
* **createPage** + **insertMDXContent** to build new pages

No additional dependencies are required. Everything works over plain HTTP with a single `x-api-key` header.

### Notes

* **Unit-aware results.** CalcTree carries physical units through every calculation. Results come back with their units (e.g. `540 kN*m`, not `540`), and the AI reports them as-is.
* **Read-only execution.** When you ask the AI to "run" a calculation, it uses `simpleCalculate`, which returns results without modifying the page. Your saved values are never changed.
* **Network access required.** The AI needs to reach `graph.calctree.com` (the GraphQL API) and `api.calctree.com` (dataset uploads). Most AI platforms run code in a sandboxed environment with restricted network access — you may need to enable outbound connections or allowlist these two domains in your platform's admin settings. Check your platform's documentation for how to configure network egress. Allowlist changes typically require starting a new session to take effect.
* **Auth errors.** An invalid API key returns a clear 401 ("Auth failed: Unauthorized"). A missing x-api-key header, however, returns a generic "Unexpected error." with no mention of auth — if you see that, check the header is being sent.