Connect Claude to Gradient Dynamics

Gradient Dynamics gives Claude tools for thermal and CFD simulation: design or upload cooling hardware (cold plates, heat sinks, battery packs, electronics enclosures), mesh it, run GPU CFD or conjugate heat transfer (CHT), and read back temperatures, pressure drops and interactive 3D results.

  • MCP server: https://api.gradient-dynamics.com/mcp (Streamable HTTP)

  • Sign in: OAuth in your browser. You can create an account during sign-in with Google or email. API keys also work.

  • Spending: every connection has a budget you choose (default 20 credits a month). See plans and limits.

Rollout status: browser sign-in (OAuth), sign-up during connection and no-sign-in discovery are being enabled in stages. Where a step says “when enabled” and it doesn’t work yet, use an API key from Studio → Developer.

Claude app (claude.ai and Claude Desktop)

On Free, Pro and Max plans:

  1. Go to Customize → Connectors and click Add custom connector.

  2. For the MCP server URL, enter https://api.gradient-dynamics.com/mcp.

  3. For Authentication, choose Sign in when needed. Claude can then list tools, templates and cost estimates straight away, and asks you to sign in the first time a tool needs your account. Sign in now also works.

  4. For OAuth client, leave Use Claude’s published identity selected.

  5. Click Add. When asked, sign in or create an account at studio.gradient-dynamics.com/connect, then choose a budget and approve.

On the Free plan you can add one custom connector.

On Team and Enterprise plans, an Owner adds the connector once:

  1. Go to Organization settings → Connectors, then Add → Custom → Web, and enter the same URL.

  2. Each member then opens Customize → Connectors, finds the connector labelled Custom and clicks Connect.

To use an API key instead (no browser sign-in):

  1. Choose No sign-in.

  2. Under Request headers, add the header authorization with the value Bearer <your key>, including the word Bearer and the space.

Request headers are a beta that not every organisation has yet. You can’t change authentication on an existing connector; remove it and add it again.

Claude Code

Sign in with OAuth (when enabled):

claude mcp add --transport http gradient-dynamics https://api.gradient-dynamics.com/mcp

Then authenticate in either of these ways:

  • In a Claude Code session, run /mcp, select gradient-dynamics, choose Authenticate and finish in your browser.

  • From your shell, run claude mcp login gradient-dynamics.

Add --scope user to use the server in every project, or --scope project to write it to the project’s .mcp.json for your team. A project .mcp.json contains no credentials.

Use an API key. Keep the key in an environment variable, never in chat or in a committed file:

export GD_API_KEY="..."   # e.g. in your shell profile or a secret manager
claude mcp add --transport http gradient-dynamics https://api.gradient-dynamics.com/mcp \
  --header "Authorization: Bearer $GD_API_KEY"

That command stores the expanded key in your local Claude Code configuration. To share a configuration without the key, use a project .mcp.json that references the variable. Claude Code expands ${GD_API_KEY} when it connects:

{
  "mcpServers": {
    "gradient-dynamics": {
      "type": "http",
      "url": "https://api.gradient-dynamics.com/mcp",
      "headers": { "Authorization": "Bearer ${GD_API_KEY}" }
    }
  }
}

Plugin (coming soon): a Gradient Dynamics plugin bundles this server with a thermal-simulation skill that teaches Claude the workflow (template or upload → inspect → estimate cost → mesh → simulate → read quality flags). Once it’s published, you’ll install it with /plugin marketplace add gradient-dynamics/agent-skills, then /plugin install gradient-dynamics@gradient-dynamics.

Check it works

Ask: “Using Gradient Dynamics, list the cold-plate templates and estimate the cost of a 2-million-cell CHT simulation. Don’t start any compute.” Claude should call list_templates and estimate_cost. Neither needs an account once no-sign-in discovery is enabled.

Then try the cold-plate quick-start.

Troubleshooting

  • HTTP 401 or “authentication required”: the tool needs your account, or your sign-in expired. The response points Claude at https://api.gradient-dynamics.com/.well-known/oauth-protected-resource/mcp. Choose Connect or Authenticate in the client (or run /mcp in Claude Code) and sign in again.

  • HTTP 402 or an error such as insufficient_allowance: the run isn’t funded. The error says why and includes links for a person:

    • insufficient_allowance: buy credits or subscribe to Core (top_up_url, upgrade_url).

    • key_budget_exhausted: raise this connection’s budget in Studio → Developer.

    • overage_cap_reached: an owner raises Core’s monthly limit on extra credits.

    • plan_limit_exceeded: for example, too many cells for your plan.

    These errors are retryable: false, so Claude should stop, not retry.

  • Never paste an API key into a chat. Use the connector settings or an environment variable. If a key leaks, revoke it in Studio → Developer.

  • Tools look out of date: reconnect the connector, or run /mcp and reconnect in Claude Code, to refresh the tool list.

More: all connection options · tool reference · data handling