# Windsurf

Connect the AstroWay API to **Windsurf** over MCP. The server is used by the Cascade assistant.

## Prerequisites

Get an API key in the [dashboard](https://api.astroway.info/dashboard/sign-up). For free testing use a sandbox `aw_test_*` key — it doesn't spend credits.

## Setup

Edit `~/.codeium/windsurf/mcp_config.json`; it's also reachable via Settings → Cascade → MCP. Note: for a remote server Windsurf uses the `serverUrl` key (not `url`). Paste one of the blocks below and **restart Windsurf**.

**Hosted (HTTP)** — zero install, Bearer-token auth:

<Code lang="json" title="~/.codeium/windsurf/mcp_config.json" code={`{
  "mcpServers": {
    "astroway": {
      "serverUrl": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_YOUR_KEY" }
    }
  }
}`} />

**Stdio (npx)** — local subprocess, env-var auth, offline-ready:

<Code lang="json" title="~/.codeium/windsurf/mcp_config.json" code={`{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_YOUR_KEY" }
    }
  }
}`} />

## Verify

In Cascade, type: "List the AstroWay tools" — or ask it to call a free reference tool, such as fetching the list of zodiac signs. If a result comes back, the connection works.

## Troubleshooting

- **401 / invalid key** — make sure the key is prefixed `aw_live_*` or `aw_test_*` and isn't revoked. Check it in the [dashboard](https://api.astroway.info/dashboard/sign-up).
- **Tools don't appear** — fully restart Windsurf and verify the `~/.codeium/windsurf/mcp_config.json` path (for hosted, use the `serverUrl` key).
- **`-32602` validation errors** (stdio) — update the package: `npm i @astroway/mcp@latest`. Schemas are regenerated from the live spec.

See all clients — [Agent setup](/en/agent-setup/).