> ## Documentation Index
> Fetch the complete documentation index at: https://connectionshub.atlastube.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NCSEA Hackathon starter kit

> Set up Connections Hub in your AI assistant or code for the NCSEA Hackathon: create your account, run the setup script, and start your project.

Welcome to the NCSEA Hackathon on **27 October**. You are one of the first people outside our team to use these tools.

Use Connections Hub from your own AI assistant or code: run real HSS connection calculations, get the verdict and a link to the live calculation. Full documentation: [Connections Hub API docs](https://connectionshub.atlastube.com/docs/api.md).

> [!NOTE]
>
> **Three steps:** 1. Create your account. 2. Run the setup script. 3. Get going on your project.
>
> Please do steps 1 and 2 before the day, so you find out early if anything needs fixing. A mentor will be on the floor to help (we'll be in the red shirts).

## Step 1. Create your account

1. Find the invite email for **NCSEA Hackathon** on Connections Hub. Accept it and **log in once**. The links your calculations return only open after you've joined (check spam if you can't find it).
2. That email also contains your **API key** - which you will need in step 2.

No emails, already have an account with this email, or lost your key? Ask a mentor.

## Step 2. Run the setup script

The installer finds the AI apps on your laptop, saves your key and connects each app to Connections Hub. It backs up each app's settings file before changing it.

**Download:** [connections-hub-installer.zip](https://github.com/owen-calcs/connections-hub-installer/releases/latest/download/connections-hub-installer.zip)

> [!WARNING]
>
> **Check before you run it**
>
> * **Using Claude Desktop?** Install **Node.js LTS** (version 22 or newer) from [nodejs.org](https://nodejs.org) first. On a work laptop this may need IT.
> * **Antivirus or a work laptop?** Add `api.calcs.com` to its allowed or excluded websites (or ask IT). Otherwise Claude Desktop can stay on "Starting" forever.

> [tab] Windows
>
> 1. In Downloads, right-click `connections-hub-installer.zip`, choose **Extract All**, then **Extract**. Don't run anything from inside the zip.
>
> 2. Copy your API key from the email.
>
> 3. Double-click **install-connections-hub** with the gear icon (Type: Windows Command Script), not the other files with the same name.
>
>    ![The install-connections-hub Windows Command Script in the extracted folder](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/windows-1-run-installer.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=1fef9abca0aa205176aec3d5ac7912d5)
>
> 4. If Windows says "The publisher could not be verified", click **Run**. If it says "Windows protected your PC", click **More info**, then **Run anyway**.
>
>    ![Windows security warning for the installer](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/windows-2-security-warning.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=099ec6a3be4e5cb48c560422880a03a5)
>
> 5. Paste your key (right-click pastes; you'll see `*` as it goes in) and press Enter. If Claude Desktop is open, the installer asks to close it: press Enter. It reopens Claude when it's done.
>
>    ![The Windows installer after it finishes](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/windows-3-installer-done.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=47d0e58f02b584b8d1d22cb59fe90fbe)

> [tab] Mac
>
> 1. Find the **connections-hub-installer** folder in Downloads (Safari unzips it; with Chrome, double-click the zip).
>
> 2. Double-click `install-connections-hub.sh`.
>
>    ![Opening install-connections-hub.sh from the Downloads folder](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/mac-1-open-installer.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=a71a105cfc0c36daeb0f5ca8caa9cab1)
>
> 3. Paste your API key from the email with **Cmd+V** and press **Return**. Nothing shows as you paste, that's expected. If Claude Desktop is open, the installer asks to quit it and reopens it afterwards.
>
>    ![The installer asking for your API key](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/mac-2-paste-key.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=1fc7dead76ed212edbc3fb77b2c39a45)
>
> 4. If your Mac asks whether Terminal can access Downloads, click **Allow**. The installer saves your key as `HUB_API_KEY` and connects the apps it finds.
>
>    ![The Mac installer after it finishes](https://mintcdn.com/connectionshub/XfsUoDSwrZxHBGhO/api/images/hackathon/mac-3-installer-done.png?fit=max\&auto=format\&n=XfsUoDSwrZxHBGhO\&q=85\&s=e2457cba667d28e7d952db90b6746a51)
>
> Double-click opened a text editor instead? See "Installer problems" below.

**Did it work?** At the end the window lists **Configured:** and your apps. If your app is there, you're set. The first time you use it, your app asks permission to use the tools: click **Allow**.

Works with Claude Desktop, VS Code (GitHub Copilot, Agent mode), Cursor, Antigravity, Claude Code and Codex CLI. It won't work with ChatGPT or Claude in a web browser, phone apps, or Microsoft Copilot in Windows, Edge, Teams or Office. Prefer one of those? Use the API route in step 3.

> [accordion] Check your app is connected
>
> * **Claude Desktop:** the installer reopens it. In Settings → Developer, **connectionshub** should say **Running**.
> * **VS Code:** open Copilot Chat, choose **Agent**, click the tools icon, tick **connectionshub**, and paste your key when VS Code asks.
> * **Cursor:** Cursor Settings → MCP (Tools & MCP in newer versions) → switch **connectionshub** on.
> * **Antigravity:** open **MCP Servers** and click **Refresh**.
> * **Your app isn't listed:** open it once, close it, rerun the installer.
> * **Needs attention** next to an app you use: set it up by hand (below). Next to one you don't use: ignore it.

> [accordion] Installer problems
>
> > [tab] Windows
> >
> > | You see | Do |
> > | - | - |
> > | Edge says "isn't commonly downloaded" | Click **…**, then **Keep**, **Show more**, **Keep anyway** |
> > | "The publisher could not be verified" or "Windows protected your PC" | Click **Run**, or **More info**, then **Run anyway** |
> > | "install-connections-hub.ps1 … does not exist" | You ran it from inside the zip. **Extract All** first |
> > | Red text "running scripts is disabled" or "not digitally signed", or the file disappears | Your company blocks scripts. Try the PowerShell line below. If that is blocked too, set your app up by hand (below) |
> >
> > PowerShell line (open PowerShell in the extracted folder and replace `YOUR_API_KEY` with your key):
> >
> > ```powershell theme={null}
> > powershell -ExecutionPolicy Bypass -File .\install-connections-hub.ps1 YOUR_API_KEY
> > ```
>
> > [tab] Mac
> >
> > | You see | Do |
> > | - | - |
> > | Double-click opens `install-connections-hub.sh` in a text editor | Run it from Terminal (steps below) |
> > | "No such file or directory" | Type `bash` and a space, drag `install-connections-hub.sh` into the Terminal window, then press **Return** |
> > | Mac asks whether Terminal can access Downloads | Click **Allow** |
> >
> > To run it from Terminal: press **Cmd+Space**, type **Terminal**, press **Return**, paste this and press **Return**. Then paste your key with **Cmd+V** (nothing shows as you paste) and press **Return**.
> >
> > ```bash theme={null}
> > bash ~/Downloads/connections-hub-installer/install-connections-hub.sh
> > ```
> >
> > Or pass the key straight in (replace `YOUR_API_KEY`):
> >
> > ```bash theme={null}
> > bash ~/Downloads/connections-hub-installer/install-connections-hub.sh YOUR_API_KEY
> > ```
>
> **Windows and Mac**
>
> | You see | Do |
> | - | - |
> | "That doesn't look like a whole key" | Copy the whole key from the email again and paste |
> | "API rejected the key" | Part of the key is missing. Copy it again and rerun |
> | "Could not reach api.calcs.com" | Antivirus or company security is blocking it. Allow `api.calcs.com`, then rerun |
> | "Claude Desktop needs Node.js 22 or newer" | Install Node.js LTS from [nodejs.org](https://nodejs.org), then rerun |
> | Claude Desktop: connectionshub stays on **Starting**, or shows **Failed** / "Server disconnected" / `InvalidHTTPResponse` | Antivirus is inspecting `api.calcs.com`, or Node.js is older than 22. Allow `api.calcs.com`, install Node.js LTS, rerun the installer. Still stuck? Try another network or laptop |
> | Your AI says it has no Connections Hub tools | Quit the app fully and reopen. Cursor: switch connectionshub on. VS Code: Agent mode and tick connectionshub |
> | 401, or connectionshub shows an error in your app | Key missing or wrong. Rerun the installer and paste the whole key. Claude Code: `claude mcp remove connectionshub`, then rerun. Scripts: open a new terminal window after running the installer |
> | Links don't open | You haven't joined NCSEA Hackathon yet. Accept the invite (check spam) and log in with the email it was sent to. Logged in with another account? Log out first |

> [accordion] Set it up by hand (only if the installer can't)
>
> For example, if your company blocks scripts.
>
> **Claude Desktop** (needs Node.js 22 or newer): Settings → Developer → Edit Config. A folder opens: right-click `claude_desktop_config.json`, choose **Open with**, then **Notepad** (Mac: TextEdit). If it's empty or only `{}`, replace everything with the block below. Otherwise paste the file and this block into Claude and ask "Merge these into one valid JSON file." Keep `Bearer ` and its space, and write `Authorization:${HUB_AUTH}` exactly. Save, quit Claude Desktop completely (Windows: right-click the Claude icon by the clock, then Quit; Mac: Cmd+Q) and reopen it.
>
> ```json theme={null}
> { "mcpServers": { "connectionshub": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.calcs.com/mcp", "--header", "Authorization:${HUB_AUTH}"], "env": { "HUB_AUTH": "Bearer paste-your-key-here", "NODE_OPTIONS": "--use-system-ca" } } } }
> ```
>
> **VS Code (GitHub Copilot):** Command Palette (Ctrl+Shift+P / Cmd+Shift+P), then **MCP: Open User Configuration**, paste this and save. Then in Copilot Chat choose **Agent**, open the tools menu, tick **connectionshub** and paste your key when asked.
>
> ```json theme={null}
> { "inputs": [ { "type": "promptString", "id": "connectionshub-api-key", "description": "Connections Hub API key", "password": true } ],
>   "servers": { "connectionshub": { "type": "http", "url": "https://api.calcs.com/mcp", "headers": { "Authorization": "Bearer ${input:connectionshub-api-key}" } } } }
> ```
>
> **Cursor:** Settings → MCP → *Add new MCP server*. Paste this with your key in place of `paste-your-key-here`, save, then switch **connectionshub** on (new servers start disabled). Put the key in the file itself: Cursor opened from the Dock or Start menu can't see a key stored in your terminal.
>
> ```json theme={null}
> { "mcpServers": { "connectionshub": { "url": "https://api.calcs.com/mcp", "headers": { "Authorization": "Bearer paste-your-key-here" } } } }
> ```
>
> **Antigravity and Windsurf (Devin Desktop):** open the raw MCP config from the app's MCP servers panel ("View raw config"), paste this with your key, save, then click **Refresh**. Windsurf is not tested by us and needs a paid Devin plan. Use its Local mode.
>
> ```json theme={null}
> { "mcpServers": { "connectionshub": { "serverUrl": "https://api.calcs.com/mcp", "headers": { "Authorization": "Bearer paste-your-key-here" } } } }
> ```
>
> **Claude Code** (store your key first: see "Scripts and code" below). Windows PowerShell:
>
> ```powershell theme={null}
> claude mcp add --scope user --transport http connectionshub https://api.calcs.com/mcp --header "Authorization: Bearer $env:HUB_API_KEY"
> ```
>
> Mac Terminal:
>
> ```bash theme={null}
> claude mcp add --scope user --transport http connectionshub https://api.calcs.com/mcp --header "Authorization: Bearer $HUB_API_KEY"
> ```
>
> Then run `claude` and type `/mcp`: you should see **connectionshub: connected**. Ran the add line before storing the key or opening a new window? Claude Code saved an empty key: run `claude mcp remove connectionshub`, then add it again.
>
> **Codex CLI** (store your key first):
>
> ```bash theme={null}
> npm i -g @openai/codex
> codex mcp add connectionshub --url https://api.calcs.com/mcp --bearer-token-env-var HUB_API_KEY
> codex
> ```
>
> Sign in with your ChatGPT account, then type `/mcp`: **connectionshub: connected**.
>
> More detail on each app, the 13 tools, and timeouts: [MCP server](https://connectionshub.atlastube.com/docs/api/mcp.md).

## Step 3. Get going on your project

Paste this into your AI:

```txt theme={null}
Use the connectionshub tools. Create a project called "<your team> first run", then run the HSS to HSS Moment Connection calculator from its Fin Plate preset. Tell me the verdict, the governing check and its utilization, and links to the calculation and the project.
```

This takes about a minute. You should get back:

* **Verdict:** `pass`, `fail`, `error` or `not_evaluated`.
* **Governing check** and its **utilization** (1.0 or less passes).
* **Links** to the calculation and the project. Open them in Connections Hub.

Next, try: *"Change the dead and live shear loads to 10 kip each, solve again, and compare."* It should now fail. Ask your AI what to change to make it pass. Want a report? Ask it to **export the project as a PDF**. To see everything you can run: *"Use the connectionshub tools. List all the calculators I can use."*

Working in a team? One laptop driving the agent works best. Everyone in your team can open the links once they've accepted their own invite. Put your team name in project names so you can find your work.

> [accordion] Ideas to build
>
> * **HSS connection optimization:** set your own loads, then try five column sizes and pick the lightest that passes.
> * **HSS truss designer**
> * **HSS education tool**
> * **From a spreadsheet:** read connections from a CSV, run each one, write a summary table with verdicts and links.
> * **Calc pack:** run a set of connections and export the project as one PDF.
> * **Explain it:** ask your AI why a check governs and what to change.
>
> Think about what you find most frustrating in your workflow to do with connections, and build something to solve it!

> [accordion] Good to know
>
> * **Units:** send values with their unit, like `"24 ft"` or `"100 kip"`. The API converts them and tells you straight away if a unit doesn't fit that input.
> * **Start from a preset** and change one or two inputs at a time. If you get `error`, go back to the preset and change one thing.
> * **Timing:** about 15 s per calculation, 30 to 40 s for truss connections. 20 options one after another is about 5 minutes; plan bigger loops around that.
> * **Deleting is switched off** for hackathon keys. Ask a mentor if you need something removed.
> * Errors: **422** means an input wasn't accepted (the message names the input and what to send, often a unit or an option). Verdict `error` means the calculator couldn't evaluate that design: go back to the preset and change one input at a time. **403 "Deletes are disabled"** is expected. **500** or a timeout: try once more, then show a mentor the error.

> [accordion] Scripts and code (API)
>
> Your AI writes a script (Python is easiest) that calls the API with your key. Full reference: [API docs](https://connectionshub.atlastube.com/docs/api.md). Good for loops, spreadsheets and batch runs. You need Python installed and somewhere to run the script: a terminal, or an AI app that runs code for you (VS Code, Cursor, Antigravity, Claude Code).
>
> > [!TIP]
> >
> > **Your key is already set.** The installer saved it as `HUB_API_KEY` on your computer, and that is all the API needs. Open a **new** terminal window (windows that were open during the install can't see it) and the examples below just work. You never paste the key into a script.
>
> > [accordion] No installer? Store your key by hand
> >
> > Windows (PowerShell: press the Windows key, type PowerShell, press Enter; no admin needed):
> >
> > ```powershell theme={null}
> > setx HUB_API_KEY "paste-your-key-here"
> > setx MAX_MCP_OUTPUT_TOKENS 100000
> > ```
> >
> > Mac (Terminal):
> >
> > ```bash theme={null}
> > echo 'export HUB_API_KEY="paste-your-key-here"' >> ~/.zshrc
> > echo 'export MAX_MCP_OUTPUT_TOKENS=100000' >> ~/.zshrc
> > ```
> >
> > **Now close this window and open a new one.** Your key only works in windows opened after you store it (Mac: or run `source ~/.zshrc`).
>
> **Test it.** Windows (PowerShell): type `curl.exe`, not `curl`:
>
> ```powershell theme={null}
> curl.exe -sS -H "Authorization: Bearer $env:HUB_API_KEY" "https://api.calcs.com/v1/templates?limit=2"
> ```
>
> Mac:
>
> ```bash theme={null}
> curl -sS -H "Authorization: Bearer $HUB_API_KEY" "https://api.calcs.com/v1/templates?limit=2"
> ```
>
> You should see two calculators and `"total"`.
>
> **Your first script.** Give your AI this:
>
> ```txt theme={null}
> Write a Python script that uses the Connections Hub API.
> My computer: <Windows or Mac>. My key is already stored in the HUB_API_KEY environment variable.
> Base URL: https://api.calcs.com. Every request sends "Authorization: Bearer <key>" (read the key from HUB_API_KEY; don't ask me for it or print it) and "X-Calcs-Actor-Type: agent".
> Docs: https://connectionshub.atlastube.com/docs/api/quickstart (plain HTTP fetch works).
> Rules:
> - Use only Python's standard library (nothing to install).
> - Start from the preset and change only the inputs I ask for; don't copy other values from the docs examples.
> - Send values with their unit, e.g. "100 kip" or "0.25 in".
> - /calculate needs an "attributes" object even when empty.
> - The verdict is summaryCheckStatus and the utilization is summaryCheck. To name the governing check, look up summaryCheckReferenceId in the calculator's outputs (GET /v1/templates/{code}).
> - Put everything in one project called "<your team> scripts" and reuse it on later runs.
> - Tell me the exact command to run the script on my computer.
> Task: run the HSS to HSS Moment Connection calculator from its Fin Plate preset and print the verdict, the governing check, its utilization and the link to the calculation.
> ```
>
> Then change the Task line to what you want to build.

> [accordion] Your own web app (API)
>
> A web page can't call `api.calcs.com` directly, so put a small server between your page and the API. Your AI can build it: do this in VS Code, Cursor, Antigravity or Claude Code (they create and start it for you). Your key is already saved as `HUB_API_KEY` by the installer (no installer? see "Scripts and code" above), so just paste this and describe your app on the last line.
>
> ```txt theme={null}
> Build me a small web app that uses the Connections Hub API.
> My computer: <Windows or Mac>. My key is already stored in the HUB_API_KEY environment variable.
> - Make a tiny local server (Python or Node, using only what's built in, nothing to install) that holds my API key and passes requests on to https://api.calcs.com. Read the key from HUB_API_KEY (don't ask me for it or print it). Never put the key in the web page.
> - The web page only talks to my local server, never to api.calcs.com directly.
> - Every API request sends "Authorization: Bearer <key>" and "X-Calcs-Actor-Type: agent".
> - Docs: https://connectionshub.atlastube.com/docs/api/quickstart (plain HTTP fetch works).
> - Rules: start from a preset and change only the inputs the page lets me change; don't copy other values from the docs examples. Send values with their unit, e.g. "100 kip" or "0.25 in". /calculate needs an "attributes" object even when empty. The verdict is summaryCheckStatus and the utilization is summaryCheck; to name the governing check, look up summaryCheckReferenceId in the calculator's outputs (GET /v1/templates/{code}).
> - Put everything in one project called "<your team> web app" and reuse it.
> - When it's done, tell me the exact command to start it on my computer and the address to open in my browser.
> App: <what you want to build>
> ```
>
> * **Putting it online** (Vercel, Netlify, Lovable)? Make the API calls from a serverless function and put the key in the host's environment settings, never in the page.
> * **Claude artifacts** and other in-chat previews can't call the API live. They can show results your AI has already fetched.

## Help and feedback

Find a mentor on the floor: we'll be in the red shirts. We'd love to hear what worked and what didn't.

Documentation: [Connections Hub API docs](https://connectionshub.atlastube.com/docs/api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.