# Connect your agent


Connect foil.tools to Claude, ChatGPT, or Grok and ask for airfoil and wing work in plain
language. Your assistant searches the airfoil library, pulls real polar data, runs
NeuralFoil analyses, optimizes sections, and analyzes 3D wings — using your foil.tools
account for quota and credits.

**Recording: Connect Claude, ChatGPT or Grok** (58 s, https://media.foil.tools/docs/connect-your-agent.dd858657f8dc.mp4)

> Ask Claude, ChatGPT or Grok for airfoil and wing work in plain language; they run the real tools against your account. No API key: paste one URL and sign in.
> Claude: Settings, Connectors, Add custom connector, paste the URL, Connect.
> ChatGPT: Developer mode, Connectors, Create, OAuth, the same URL.
> Grok: grok.com/connectors, New Connector, Custom.
> Search, polars, 2D analysis and saving are free. Credits only for optimization and 3D wing runs, the same as on the pages.

> **You are not charged for the conversation.** Your AI subscription pays for the chat
> itself. foil.tools charges credits only for the heavy engineering runs — optimization and
> 3D wing analysis. Searching, browsing and 2D analysis are free.

## Before you start

1. A **free foil.tools account** — [sign up](https://foil.tools/dashboard). This is what
   the connector authorizes against, and it is where your credits and saved designs live.
2. A plan on your assistant that allows custom connectors (see each section below).
3. Credits only if you want optimization or 3D wing analysis. Every account gets a free
   monthly allowance first — you do not need to buy anything to try it.

You do **not** need an API key. The connector signs you in with your existing foil.tools
account. Keys remain supported, and are the right answer for scripts and for clients that
cannot do OAuth — see [Any other MCP client](#any-other-mcp-client).

---

## Claude

Works on claude.ai, the desktop app, and mobile.

1. Open **Settings** (your name, bottom-left) → **Connectors**, under the *Customize*
   heading.
2. Top right, click **Add ▾** → **Add custom connector**. (It is a dropdown, not a button —
   easy to miss.)
3. Paste the URL:

   ```
   https://foil.tools/api/mcp
   ```

4. Click **Add**, then **Connect**. A foil.tools sign-in page opens.
5. Sign in and approve. The foil.tools tools appear in your chats.

> **The grant covers your whole account.** There is no read-only connection and no spending
> ceiling. An approved connector can run optimization and wing analysis, which spend
> credits, can **save airfoils, wing designs and analyses into your account**, and can
> **read back everything already saved there** — names, dates, planform parameters and
> stored results. It cannot delete or overwrite anything — saving only ever adds. If that
> is not what you want, disconnect it. (An `ft_` API key has always worked the same way.)

Try it with: *"Using foil.tools, find me a section for a hydrofoil at Re 500,000 and CL 0.6,
and show me its drag polar."*

### Claude Code

```bash
claude mcp add --transport http foiltools https://foil.tools/api/mcp
```

No `--header` and no key — Claude Code opens the same sign-in on first use.

---

## ChatGPT

Custom connectors live behind **Developer mode**, which is web-only and needs a Plus, Pro,
Business, Enterprise, or Edu plan. On Business and Enterprise, an admin may have to allow
custom connectors first (**Workspace Settings → Permissions & Roles → Connected Data →
Create custom MCP connectors**).

1. Open **Settings → Apps → Advanced settings** and turn on **Developer mode**.
2. Go to **Settings → Connectors** and click **Create**.
3. Fill in:

   | Field | Value |
   |---|---|
   | Name | `foil.tools` |
   | Description | `Airfoil and wing design tools. Search a library of thousands of airfoils, retrieve real lift and drag polars, run NeuralFoil 2D analysis, optimize airfoil sections, and analyze 3D wings.` |
   | MCP server URL | `https://foil.tools/api/mcp` |
   | Authentication | **OAuth** |

   The description is not decoration — ChatGPT reads it when deciding whether the connector
   is relevant to what you asked. Use the wording above.

4. Click **Create**, then **Connect**, and sign in to foil.tools.

### Without Developer mode

foil.tools still appears in **Deep Research** and company-knowledge searches, where it can
search the airfoil library and read airfoil pages. It cannot run analyses, optimizations, or
wing studies there — those need Developer mode. Nothing is broken if you see only search
results; that is the mode working as designed.

---

## Grok

Connectors are available to all Grok users (xAI docs, 2026-07-17 — they were paid-tier
only earlier). On Grok Business and Enterprise a team admin has to provision the connector
in the cloud console before members can use it.

1. Go to [grok.com/connectors](https://grok.com/connectors).
2. Click **New Connector**, then **Custom**.
3. Paste `https://foil.tools/api/mcp` and complete the sign-in.

Grok discovers the tool list automatically.

---

## Any other MCP client
<a id="any-other-mcp-client"></a>

Cursor, Zed, your own scripts, and other agent frameworks connect with an API key instead of
signing in. Generate one at **[Dashboard → API Keys](https://foil.tools/dashboard)** (free
account, up to 5 keys).

```json
{
  "mcpServers": {
    "foiltools": {
      "type": "http",
      "url": "https://foil.tools/api/mcp",
      "headers": { "Authorization": "Bearer ft_YOUR_KEY" }
    }
  }
}
```

An API key carries **full access to your account's credits** — treat it like a password,
and prefer signing in through a connector where you have the choice. Keys do not expire;
revoke them from the dashboard when you are done with them.

---

## What your assistant can do

> **Costs below are a snapshot; `/connectors` is the authority.** That page interpolates
> `CREDIT_COSTS` (`app/utils/credits.ts`), `ANALYZE_HOURLY_LIMIT` (`app/utils/rate-window.ts`)
> and `MCP_HOURLY_LIMIT` (`app/utils/mcp-ratelimit.ts`) at render time, so it cannot go
> stale. Markdown cannot import, so this table can — re-check it against those constants
> whenever pricing or a rate limit moves, and prefer linking readers to
> [foil.tools/connectors](https://foil.tools/connectors) over copying numbers out of here.

| Tool | What it does | Cost |
|---|---|---|
| `search_airfoils` | Search thousands of airfoils by name | Free |
| `get_airfoil` | Geometry, thickness, camber, coordinates | Free |
| `get_polar` | Stored NeuralFoil lift/drag/moment curves | Free |
| `search_by_operating_point` | Find airfoils that perform at a Re/CL | Free |
| `find_airfoil` | Weighted multi-point selector — scored on drag, Clmax, stall gentleness, pitching moment, efficiency and L/D placement; a point can be marked a constraint (checked, not scored) for a stall or load requirement | Free |
| `analyze_airfoil` | NeuralFoil 2D analysis, optional flap | Free, rate-limited |
| `optimize_airfoil` | Inverse design — optimizes a section for your operating points | **3 credits** |
| `analyze_wing` | 3D wing analysis (AeroBuildup or VLM), and where the wing stalls first | **1–3 credits** |
| `analyze_trim` | Trim an aircraft: a wing plus a stabiliser (saved designs or station tables) about a CG, on LiftingLine — trim angle, stabiliser setting, per-surface loads, static margin, required thrust; one speed or a sweep. **Paid-only: no free allowance, unlimited on Pro** | **2 credits** a trim point, **3** a sweep |
| `save_airfoil` | Save a section to your account | Free |
| `save_wing_design` | Save a wing station table to your account | Free |
| `save_wing_analysis` | Save an analysis run to your account | Free |
| `list_saved_airfoils` | What is already in your account — names and dates, not geometry | Free |
| `get_saved_airfoil` | One saved section back, with its CST parameters | Free |
| `list_wing_designs` | Your saved wings, with their planform parameters | Free |
| `get_wing_design` | One saved wing back in full, splines included | Free |
| `list_wing_analyses` | Your saved runs, optionally filtered to one design | Free |
| `get_wing_analysis` | One saved run back in full — no credits to re-read | Free |

Ask your assistant to save anything worth keeping — *"save that as 'hydrofoil v2'"*. Saved
items appear under Dashboard → Foils / Wings / Wing Analyses. A free account holds 10 of
each.

It can also read them back. *"What wings have I saved?"* works in a new conversation, and
*"open the 1.5 m glider and analyze it at 15 m/s"* works without describing the wing again.
Reading a saved wing analysis costs nothing, so a run you already paid for does not have to
be repeated.

> **The read tools and `analyze_trim` are new.** Your assistant only sees a tool added after
> you connected once you disconnect and reconnect the connector — a connected client caches
> the tool list, and this server has no session to push a change down. See the last row of
> [Troubleshooting](#troubleshooting) for why.

Free monthly allowances apply before credits are touched. Check what is left any time at
[Dashboard → Credits](https://foil.tools/dashboard?tab=credits), or just ask your assistant
how many credits you have.

3D wing analysis with VLM can take **several minutes**. That is the solver working, not a
hang.

---

## Managing and revoking access

- **Disconnect a connector** in your assistant's own settings — Claude, ChatGPT and Grok
  each list it under Connectors. That is what stops access.
- **There is no per-connector permission to change.** The grant is all-or-nothing over the
  account, so "reconnect with fewer permissions" is not a thing you can do.
- **API keys** are separate — revoke those under
  [Dashboard → API Keys](https://foil.tools/dashboard).

Revoking never touches your saved foils, wing designs, or credits.

---

## Troubleshooting

| What you see | What it means |
|---|---|
| "Failed to connect" / "Could not reach server" | Check the URL is exactly `https://foil.tools/api/mcp` — no trailing slash, no `/sse`. |
| Sign-in opens but ends on an error | You are probably signed into a different foil.tools account in that browser. Sign out at foil.tools and retry. |
| The assistant never uses the tools | Ask for foil.tools by name once: *"Using foil.tools, …"*. In ChatGPT, check the connector Description matches the wording above. |
| ChatGPT only searches and never analyses | Developer mode is off, or you are in Deep Research. Both limit the connector to search and fetch. |
| "Monthly quota exceeded" | The free allowance for that tool is used up. Buy credits, or wait for the reset on the 1st. |
| "Insufficient credits" | Top up at Dashboard → Credits, or ask your assistant to send you a checkout link. |
| A wing analysis times out | VLM at high panel counts is slow. Ask for AeroBuildup, or fewer spanwise panels. |
| It quotes a sweep angle that looks wrong | Ask it to report quarter-chord sweep explicitly — the designer's `sweep` control is not the quarter-chord angle. |
| Everything 401s in a script | An `ft_` key is passed as `Authorization: Bearer ft_...`. Regenerate it if in doubt. |
| A connector 401s after working fine | The sign-in expired or was revoked. Disconnect and reconnect in your assistant's settings. |
| A tool the docs mention isn't offered | Your client cached the tool list at connect time. The server is stateless and cannot push a `tools/list_changed` notification, so tools added since you connected only appear after you disconnect and reconnect. |

Still stuck: [foil.tools/contact](https://foil.tools/contact).

---

## Privacy and safety

- A connector can see only what the tools return — the public airfoil library, your own
  saved designs, and your quota. It cannot read your email, files, or anything else.
- It can **add** to your saved airfoils, wing designs and analyses. It cannot delete or
  overwrite them; every save creates a new entry, and deleting stays a thing you do in the
  dashboard.
- foil.tools never sees your conversation. Your assistant sends tool calls; we answer them.
- **An assistant can spend your credits without asking again.** Approving the connector is
  the last confirmation you get, and an assistant deciding on its own to run twelve
  optimizations is a real possibility. Your monthly free allowance absorbs the first few;
  past that it is your credit balance. Keep an eye on
  [Dashboard → Credits](https://foil.tools/dashboard?tab=credits), or just ask how many
  credits are left.
- Anything an assistant hands you is a starting point for engineering judgement, not a
  substitute for it. Validate before you cut material.
