Terms
- Calculator: the template you pick, such as the HSS Steel Base Plate.
list_calculatorsandget_calculatorfind and describe them. The 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:
sheetIdidentifies it andsheetUrllinks to it. - Project: holds your calculations.
create_projectmakes one; keep related calculations in the same project.
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 and the sheet lifecycle in the REST API.
Connection details
Claude Code
$env: and keep the command on one line:
$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:
~/.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:
.cursor/mcp.json
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:
.vscode/mcp.json
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 themcp-remote bridge, which needs Node.js. 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.
claude_desktop_config.json
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: withHUB_API_KEY set in your environment, 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):
~/.codex/config.toml
~/.gemini/settings.json. Its default tool timeout is 10 minutes, so it needs no timeout setting:
~/.gemini/settings.json
Other clients
Any MCP client that supports Streamable HTTP and lets you set a customAuthorization header can connect with the details in 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 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: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 fromsummaryCheckStatus:
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 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.
The MCP server has no tools for bulk calculate or deleting. 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.