Skip to main content
The Model Context Protocol (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.

Terms

  • Calculator: the template you pick, such as the HSS Steel Base Plate. list_calculators and get_calculator find 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: 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 and the sheet lifecycle in the REST API.

Connection details

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

In Windows PowerShell, set the key with $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:
In Windows PowerShell:
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:
.cursor/mcp.json
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:
.vscode/mcp.json
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 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
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:
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 CLI, in ~/.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 custom Authorization 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:
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: 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.