# GO AI Chat — MCP server

> Connect GO AI Chat to any MCP client. GO AI Chat for Mac runs an on-device Model Context Protocol (MCP) server that exposes image, video, and media generation tools to clients like Claude Code, Cursor, and Claude Desktop. Every generation is metered against your signed-in GO AI Chat Lab-token balance.

This is the developer guide for the MCP server built into [GO AI Chat](https://__CANONICAL_HOST__/chat). The same "How to connect a client" page is linked from Settings → MCP Server inside the app.

- App (host): [GO AI Chat on the Mac App Store](https://apps.apple.com/app/id6742322421)
- Availability: **Mac only** (Mac Catalyst); the server runs on-device
- Endpoint: `http://127.0.0.1:8722/mcp` (default port 8722, configurable ≥ 1024)
- Transport: streamable HTTP (`"type": "http"`)
- Auth: `Authorization: Bearer <token>` (a per-install pairing token you can regenerate)
- Server name reported to clients: `goai-chat`

---

## Connect in three steps

1. **Enable the server.** In GO AI Chat for Mac, open **Settings → MCP Server** and turn on **Enable MCP Server**. The status turns green and shows `http://127.0.0.1:8722/mcp`.
2. **Copy your pairing token.** In the **Pairing Token** section, tap **Copy**. Treat it like a password. **Regenerate** rolls the token and revokes any client still using the old one.
3. **Add it to your client.** Use the snippets below, replacing `<YOUR_TOKEN>` with your token (the in-app snippets already include the live token).

### Claude Code

```
claude mcp add --transport http goai-chat http://127.0.0.1:8722/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
```

### Cursor / Claude Desktop / JSON-config clients

Add to `mcp.json` (Cursor) or `claude_desktop_config.json` (Claude Desktop):

```json
{
  "mcpServers": {
    "goai-chat": {
      "type": "http",
      "url": "http://127.0.0.1:8722/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}
```

Any MCP client that supports the HTTP transport with a Bearer Authorization header works.

---

## Tools (13)

Powered by Grok for generation; Studio color grading runs on-device.

### Generate

| Tool | Description | Cost |
|---|---|---|
| `generate_image` | Text-to-image in a chosen style preset | 1 token |
| `transform_image` | Image-to-image restyle, incl. inpainting via a PNG mask | 1 token |
| `generate_video` | Text-to-video clip (returns a job id to poll) | per second |
| `summarize_media` | Summarize a YouTube URL or a PDF/MP4 file (≤ 50 MB) | 5 tokens |

### Studio

| Tool | Description | Cost |
|---|---|---|
| `studio_create_image` | Create an image from a prompt (no style preset) | 1 token |
| `studio_edit_image` | Edit a reference image with a prompt | 2 tokens |
| `studio_image_to_video` | Animate a reference image into a video | per second |
| `studio_edit_video` | Edit an existing video (≤ 15 s) with a prompt | per second |
| `studio_adjust_image_colors` | Professional color grading on an image, on-device | 1 token |
| `studio_adjust_video_colors` | Professional color grading on a video, on-device | 3 tokens |

### Utility (free, read-only)

| Tool | Description | Cost |
|---|---|---|
| `get_token_balance` | Lab/chat token balances, tier, and 720p eligibility | Free |
| `get_job_status` | Status, progress, or result of an async job | Free |
| `list_generation_options` | Full catalog: styles, aspect ratios, durations, costs | Free |

---

## Token costs

Generations spend from the same Lab-token balance the app uses. Read-only tools are free.

- Images: 1 token (`studio_edit_image` is 2).
- Color grading: 1 token (image) / 3 tokens (video).
- Media summaries: 5 tokens.
- Video: `max(10, round(seconds × 2.5))` tokens — e.g. an 8-second clip costs 20 tokens.
- 720p video requires an active subscription.
- Check your balance with `get_token_balance`; call `list_generation_options` for the full machine-readable catalog.

---

## How it works / security

- **Localhost only.** The server binds to `127.0.0.1` — it is not exposed to your network or the internet. Clients connect from the same Mac.
- **Bearer-token auth.** Every request must carry the pairing token. Regenerate it to revoke access immediately.
- **Metered.** Generation tools draw from your signed-in GO AI Chat Lab-token balance; read-only tools never spend tokens.
- **Async video.** Video tools return a job id immediately — poll `get_job_status` until the result is ready.
- **Port handling.** Default port is 8722; set any port ≥ 1024. If the chosen port is busy the server auto-increments to the next free one.
- **Mac-only today.** The server runs inside GO AI Chat for Mac (Mac Catalyst). Keep the app open while a client is connected. Generations also appear in your in-app history across devices.

---

## Links

- MCP guide (this page): https://__CANONICAL_HOST__/mcp
- GO AI Chat detail page: https://__CANONICAL_HOST__/chat
- Mac App Store: https://apps.apple.com/app/id6742322421
- Support: support@goaichats.com
- Back to GO AI homepage: https://__CANONICAL_HOST__/