Connect Cursor to Gradient Dynamics

Give Cursor’s agent tools for thermal and CFD simulation: design or upload cooling hardware (cold plates, heat sinks, battery packs, electronics), mesh it, run GPU CFD or conjugate heat transfer, and open interactive 3D results.

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

  • Sign in: OAuth in your browser (when enabled). 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. Until they’re on for you, use the API key form below with a key from Studio → Developer.

Sign in with OAuth (when enabled)

Add the server to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in one project. Keep any other servers already in the file:

{
  "mcpServers": {
    "gradient-dynamics": {
      "url": "https://api.gradient-dynamics.com/mcp"
    }
  }
}
  1. Open Cursor’s MCP settings. The server asks you to log in.

  2. Start the login. Cursor opens your browser at studio.gradient-dynamics.com/connect.

  3. Sign in or create an account, choose a budget and approve.

Cursor finds our OAuth endpoints itself and registers dynamically; you don’t need an auth block or a client ID.

Once Gradient Dynamics is listed in the Cursor Marketplace, Add to Cursor installs the server and starts the same login.

Use an API key

Reference an environment variable rather than writing the key into the file:

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

Cursor must inherit GD_API_KEY from the environment it was started in. Setting the variable in a terminal doesn’t update a Cursor window that is already open, so restart Cursor after setting it. Never commit a project mcp.json that contains a real key.

Check it works

Ask the agent: “Using Gradient Dynamics, list the cold-plate templates and estimate the cost of a 2-million-cell CHT simulation. Don’t start any compute.” It should call list_templates and estimate_cost.

Then try the cold-plate quick-start.

Troubleshooting

  • 401 or a login prompt: the tool needs your account, or the sign-in expired. The server’s 401 points to https://api.gradient-dynamics.com/.well-known/oauth-protected-resource/mcp, and Cursor starts the login from there. With an API key, check that GD_API_KEY is visible to Cursor and that the key hasn’t been revoked or expired.

  • 402 or an error such as insufficient_allowance: the run isn’t funded. The error includes top_up_url or upgrade_url for a person to open, or tells you to raise the key’s budget (key_budget_exhausted). These errors are retryable: false; don’t retry, and don’t switch to another key to get round a budget.

  • Never paste an API key into chat. If a key leaks, revoke it in Studio → Developer.

  • Tools missing or stale: toggle the server off and on in Cursor’s MCP settings to refresh the tool list.

More: tool reference · data handling · headless and CI