> ## 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.

# MCP server

> Connect Claude Code, Cursor, VS Code or another AI agent to the Connections Hub API through the Calcs.com MCP server.

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI agents such as Claude Code, Cursor and GitHub Copilot call external tools. The Calcs.com MCP server offers the Connections Hub API as 13 tools: an agent can find a calculator, read its inputs, create a project, run the calculation on the same engine as the app, and hand back the result with a link to the calculation. Each tool carries instructions for the agent, including the unit rules, so you do not need to paste them into your prompt.

The MCP server uses the same API key as the REST API. To get one, see [Authentication](https://connectionshub.atlastube.com/docs/api/authentication.md).

## Terms

* **Calculator**: the template you pick, such as the [HSS Steel Base Plate](https://connectionshub.atlastube.com/docs/calculators/base-plates/us/hss-base-plate.md). `list_calculators` and `get_calculator` find and describe them. The [template codes](https://connectionshub.atlastube.com/docs/api.md#hub-calculator-template-codes) of the Hub calculators are listed on the API introduction.
* **Calculation**: one instance of a calculator in a project, with its own inputs and results. It is what the app shows. In the API a calculation is called a sheet: `sheetId` identifies it and `sheetUrl` links to it.
* **Project**: holds your calculations. `create_project` makes one; keep related calculations in the same project.

An agent makes a calculation in one of two ways: step by step (`create_calculation`, then `set_calculation_inputs`, then `solve_calculation`), or in a single call with `create_and_solve_calculation`. To change a calculation, the agent updates it with `set_calculation_inputs` and `solve_calculation` rather than creating a new one. These are the same two paths as [calculate](https://connectionshub.atlastube.com/docs/api/guides/templates.md) and the [sheet lifecycle](https://connectionshub.atlastube.com/docs/api/guides/sheet-lifecycle.md) in the REST API.

## Connection details

| | |
| - | - |
| Server URL | `https://api.calcs.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | `Authorization: Bearer YOUR_API_KEY` header, with your Connections Hub API key |
| OAuth | Not supported |
| Tool timeout | At least 120 seconds (see [Timeouts](#timeouts)) |

> [!WARNING]
>
> Keep your API key out of files you commit. The Cursor, VS Code, Codex and Gemini setups below read the key from an environment variable or prompt for it, so their config files hold no key. Claude Code and Claude Desktop store the key in your user configuration, outside any project.

## Claude Code

```bash theme={null}
export HUB_API_KEY="YOUR_API_KEY"
claude mcp add --transport http connectionshub https://api.calcs.com/mcp \
  --header "Authorization: Bearer $HUB_API_KEY"
```

In Windows PowerShell, set the key with `$env:` and keep the command on one line:

```powershell theme={null}
$env:HUB_API_KEY = "YOUR_API_KEY"
claude mcp add --transport http connectionshub https://api.calcs.com/mcp --header "Authorization: Bearer $env:HUB_API_KEY"
```

`$env:` lasts for the current window. To keep the key for windows you open later, run `setx HUB_API_KEY "YOUR_API_KEY"` and open a new window.

Run `/mcp` inside Claude Code to check that `connectionshub` is connected.

`get_calculator` returns a calculator's full input list, and on the HSS connection calculators that list can pass Claude Code's default limit on tool output. Raise the limit before you start Claude Code:

```bash theme={null}
export MAX_MCP_OUTPUT_TOKENS=100000
```

In Windows PowerShell:

```powershell theme={null}
$env:MAX_MCP_OUTPUT_TOKENS = "100000"
```

Even with the higher limit, Claude Code saves the input list of most connection calculators (70 to 650 KB) to a file, and the agent searches that file for the fields it needs. If Claude Code asks to read a file under `~/.claude/projects/…/tool-results`, allow it. A calculation that starts from a preset (`list_presets`) and sends only the fields you change takes about a minute, and `validate_inputs` checks those fields before anything is created. When the agent first reads a large calculator's full input list, expect 3 to 10 minutes.

## Cursor

Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project), with `HUB_API_KEY` set in your environment:

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "connectionshub": {
      "url": "https://api.calcs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HUB_API_KEY}"
      }
    }
  }
}
```

Cursor adds a new MCP server switched off. Open **Cursor Settings**, find `connectionshub` in the MCP list and switch it on.

Cursor reads `HUB_API_KEY` from the environment it was started in, so start it from a terminal where the variable is set (for example `cursor .`). Opened from the macOS Dock, Cursor does not see variables set in a terminal: it sends an empty key and the server replies `401 Unauthorized`. To open Cursor from the Dock, write the key itself in `~/.cursor/mcp.json`, your user-level configuration outside any project.

## VS Code (GitHub Copilot)

Add the server to `.vscode/mcp.json`. VS Code prompts for the key the first time the server starts and stores it securely:

```json .vscode/mcp.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}"
      }
    }
  }
}
```

Use Copilot Chat in Agent mode and turn on the `connectionshub` tools under Configure Tools. On Copilot Business or Enterprise, an organization admin must first enable MCP servers in Copilot policy, which is off by default.

## Claude Desktop

Claude Desktop connects to this server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which needs [Node.js](https://nodejs.org). Open **Settings → Developer → Edit Config**. The file already holds Claude Desktop's own settings. Keep them, and add the `"mcpServers"` part below after them, with a comma at the end of the line before it. If the file already has `"mcpServers"`, add only the `"connectionshub"` part inside it.

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "connectionshub": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.calcs.com/mcp",
        "--header",
        "Authorization:${CALCS_AUTH}"
      ],
      "env": {
        "CALCS_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Write `Authorization:${CALCS_AUTH}` exactly as shown, with no space after the colon. On Windows, Claude Desktop does not escape spaces inside arguments when it starts `npx`, so the space lives inside the `CALCS_AUTH` value instead. Restart Claude Desktop after saving.

## Codex CLI and Gemini CLI

Codex CLI: with `HUB_API_KEY` set in your environment, run:

```bash theme={null}
codex mcp add connectionshub --url https://api.calcs.com/mcp --bearer-token-env-var HUB_API_KEY
```

Run `/mcp` inside Codex to check that `connectionshub` is connected. The command writes the server to `~/.codex/config.toml`. Codex stops a tool call after 60 seconds by default, which is too short for the HSS truss calculator, so add `tool_timeout_sec` to that entry (or write the whole entry yourself instead of running the command):

```toml ~/.codex/config.toml theme={null}
[mcp_servers.connectionshub]
url = "https://api.calcs.com/mcp"
bearer_token_env_var = "HUB_API_KEY"
tool_timeout_sec = 120
```

Gemini CLI, in `~/.gemini/settings.json`. Its default tool timeout is 10 minutes, so it needs no timeout setting:

```json ~/.gemini/settings.json theme={null}
{
  "mcpServers": {
    "connectionshub": {
      "httpUrl": "https://api.calcs.com/mcp",
      "headers": {
        "Authorization": "Bearer $HUB_API_KEY"
      }
    }
  }
}
```

## Other clients

Any MCP client that supports Streamable HTTP and lets you set a custom `Authorization` header can connect with the details in [Connection details](#connection-details).

## Clients that cannot connect yet

* **ChatGPT** connectors sign users in with OAuth or use no authentication. They cannot send an API key, so they cannot use this server.
* **claude.ai custom connectors** (the connector settings in Claude on the web and in Claude Desktop) also expect OAuth. Sending a fixed header is a limited beta that only an organization Owner can set, with one key shared by the whole organization. Use the [Claude Desktop](#claude-desktop) setup instead.
* **Microsoft 365 Copilot and Copilot Studio** are not covered here yet. Adding an MCP server there can be blocked by your organization's data policies or need approval in the Microsoft 365 admin center, so expect to involve your tenant admin.

## Try it

Once the server is connected, ask your agent for a connection in plain language, for example:

```text theme={null}
Create a project called "MCP test" and run an HSS to HSS moment connection
from the Fin Plate preset, LRFD, with an HSS8X4X.375 beam on an HSS10X10X.500
column. Tell me whether it passes and give me the link to the calculation.
```

The agent looks up the calculator, creates the project and the calculation, and reports the governing check with the `sheetUrl`. Open the link to review the calculation in the app.

## Reading the result

Calculation results use the same fields as the REST API. Read the verdict from `summaryCheckStatus`:

| `summaryCheckStatus` | Meaning |
| - | - |
| `pass` | The governing check passed: `summaryCheck` is `true`, or a utilisation from 0 to 1 |
| `fail` | The governing check evaluated and failed: `summaryCheck` is `false`, or a utilisation above 1. `summaryCheckFailReasons` says why |
| `error` | The governing check could not be evaluated, for example with no loads applied. Treat it as not passing |
| `not_evaluated` | The calculator defines no governing check |

Do not read `passed` as the verdict. It is deprecated, and a failing calculation can report `true`.

Numbers go in as strings tagged with the field's published units, for example `"24 ft"` or `"100 kip"`. A field whose units are `null` takes a plain number. The tool instructions already tell the agent this, so you can give values in your prompt the way you would write them.

## Timeouts

Most calculations finish in 5 to 8 seconds. The HSS connection calculators take 11 to 15 seconds, and the [General HSS Truss Connection](https://connectionshub.atlastube.com/docs/calculators/truss/us/hss-truss-connection.md) 30 to 40 seconds. Make sure your client allows a tool call at least 120 seconds. Claude Code and Gemini CLI allow 10 minutes by default; Codex CLI allows 60 seconds unless you raise it as shown above.

`solve_calculation` is safe to retry. `create_and_solve_calculation` is not: if it times out on your side it may still have created the calculation, and a retry creates a second one. The tool descriptions steer the agent to the `create_calculation`, `set_calculation_inputs`, `solve_calculation` path for slow calculators.

## Tools

Each tool calls one Connections Hub API endpoint.

| Tool | What it does | REST endpoint |
| - | - | - |
| `list_calculators` | Lists the calculators your API key can run. The agent pages through all of them. | [List templates](https://connectionshub.atlastube.com/docs/api/reference/templates/list-available-calculation-templates.md) |
| `get_calculator` | Returns a calculator's input fields, units, options, outputs and presets. | [Get template details](https://connectionshub.atlastube.com/docs/api/reference/templates/get-template-details.md) |
| `list_presets` | Lists a calculator's presets: complete sets of valid inputs. | [Get template presets](https://connectionshub.atlastube.com/docs/api/reference/templates/get-template-presets.md) |
| `validate_inputs` | Checks inputs against a calculator without running it. | [Validate inputs](https://connectionshub.atlastube.com/docs/api/reference/templates/validate-inputs-against-a-template.md) |
| `create_project` | Creates a project to hold calculations. | [Create project](https://connectionshub.atlastube.com/docs/api/reference/projects/create-project.md) |
| `create_and_solve_calculation` | Creates a calculation and solves it in one call, and returns the results and the calculation link. | [Run a calculation](https://connectionshub.atlastube.com/docs/api/reference/templates/run-a-calculation-using-a-template.md) |
| `create_calculation` | Creates an unsolved calculation. | [Create sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/create-sheet.md) |
| `set_calculation_inputs` | Writes input values to a calculation. | [Update sheet inputs](https://connectionshub.atlastube.com/docs/api/reference/sheets/update-sheet-inputs.md) |
| `solve_calculation` | Solves a calculation and returns the results. | [Solve sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/solve-sheet.md) |
| `get_calculation` | Reads a calculation's inputs, results and status. | [Get sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/get-sheet.md) |
| `list_project_calculations` | Lists the calculations in a project. | [List project sheets](https://connectionshub.atlastube.com/docs/api/reference/projects/list-project-sheets.md) |
| `export_project_pdf` | Starts a PDF export of a project. | [Export project to PDF](https://connectionshub.atlastube.com/docs/api/reference/projects/export-project-to-pdf.md) |
| `get_export` | Checks an export and returns the download link when it is ready. | [Get export status](https://connectionshub.atlastube.com/docs/api/reference/projects/get-export-status.md) |

The MCP server has no tools for [bulk calculate](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md) or [deleting](https://connectionshub.atlastube.com/docs/api/guides/deleting.md). Use the REST API for those.

Every calculation result includes a `sheetUrl` that opens the calculation in the app, so you can check the calculation the agent ran.


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