# Windsurf recipes

> Add BlueBot’s MCP server to Windsurf so its agent can send and read texts.

Three recipes for Windsurf. Each names its trigger and the BlueBot step, lists the fields to map and says how to test it with your own number before anyone else gets a text.

## How Windsurf connects

- **[MCP](https://usebluebot.com/docs/mcp)**: BlueBot’s MCP server gives the assistant tools to send texts, read conversations and check your Mac.
- **[API](https://usebluebot.com/docs/api)**: Your own code calls BlueBot’s REST API and listens to its signed webhooks.

## Text me when the deploy script finishes

| Part             | What it is                              |
| ---------------- | --------------------------------------- |
| Trigger          | You ask Windsurf’s agent                |
| Action           | The assistant calls BlueBot’s MCP tools |
| Connects through | [MCP](https://usebluebot.com/docs/mcp)                        |

### Steps

1. Add BlueBot’s MCP server to Windsurf’s MCP configuration with your API key.
2. Ask: “Run the deploy script and text me when it’s done.”
3. The agent calls send_text to your number once you approve it.

### Test it

Ask the assistant to text your own number first: “Text me at +1 555 555 0123 to say the setup works.” It shows the message BlueBot returned, and the text arrives on your phone from your own number.

## Ask how your texts did this week

| Part             | What it is                              |
| ---------------- | --------------------------------------- |
| Trigger          | You ask Windsurf’s agent                |
| Action           | The assistant calls BlueBot’s MCP tools |
| Connects through | [MCP](https://usebluebot.com/docs/mcp)                        |

### Steps

1. Ask: “How many texts did I send this week, and how many got a reply?”
2. The agent calls get_analytics and answers with what was sent, delivered, read and replied to.

### Test it

Ask the assistant to text your own number first: “Text me at +1 555 555 0123 to say the setup works.” It shows the message BlueBot returned, and the text arrives on your phone from your own number.

## Send a text from a shell script

| Part             | What it is                        |
| ---------------- | --------------------------------- |
| Trigger          | Your script reaches its last line |
| Action           | `POST /v1/messages`               |
| Connects through | [API](https://usebluebot.com/docs/api)                  |

### Steps

1. Have the agent add a call to POST /v1/messages with curl at the end of the script.
2. Send your own number as to and a short message as text.
3. Keep the API key in an environment variable so it never sits in the script.

### Map the fields

| BlueBot field | Map it to                                                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`          | The person’s mobile number from Windsurf. US numbers can leave off the +1.                                                                    |
| `text`        | Backup finished: 14 GB copied.                                                                                                                |
| `metadata`    | `source` set to `windsurf`, and `record_id` set to the record’s id, so the status and reply webhooks for this text can find the record again. |
| `service`     | Auto, the default: iMessage when the person uses it, otherwise SMS through your iPhone.                                                       |

```bash
curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: windsurf-1042" \
  -d '{
    "to": "+15555550123",
    "text": "Backup finished: 14 GB copied.",
    "metadata": {
      "source": "windsurf",
      "record_id": "1042"
    }
  }'
```

```ts
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const message = await client.messages.send({
  to: '+15555550123',
  text: 'Backup finished: 14 GB copied.',
  metadata: {
    source: 'windsurf',
    record_id: '1042',
  },
}, { idempotencyKey: 'windsurf-1042' });
console.log(message);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

message = client.messages.send(
    to="+15555550123",
    text="Backup finished: 14 GB copied.",
    metadata={
        "source": "windsurf",
        "record_id": "1042",
    },
    idempotency_key="windsurf-1042",
)
print(message)
```

### Test it

Run the request with your own number in `to`. A text arrives on your phone from your own number.

## Before you turn it on

- Text only people who asked to hear from you. Anyone who replies STOP goes on your stop list, and BlueBot cancels texts to them. [Stop words](https://usebluebot.com/docs/concepts/stop-words)
- A text that can’t go yet waits with a hold rather than failing: quiet hours, your Mac away, a daily limit. [Holds](https://usebluebot.com/docs/concepts/holds)
- [Windsurf with BlueBot](https://usebluebot.com/integrations/windsurf) on the integrations page says what else the two do together.