# Ensemble MCP

שרת ה-MCP של Ensemble מחבר את הסוכן שאתם כבר עובדים איתו (Claude, ChatGPT, Cursor, Claude Code, Manus,
Gemini CLI) לכל צוות השיווק: הסטודיו, המשרד, המוח ומפל התוכן.

- **כתובת:** `https://<הדומיין שלכם>/api/mcp`
- **תעבורה:** Streamable HTTP, בלי סשן (stateless), תשובות JSON. `GET` ו-`DELETE` מחזירים 405.
- **אימות:** `Authorization: Bearer ens_live_…` (מפתח מ-`/account/developers`). המפתח מתקבל **רק בכותרת**,
  אף פעם לא בכתובת.
- **מגבלת קצב:** 60 בקשות לדקה למפתח, משותפת עם ה-REST API.
- **הסקיל:** `https://<domain>/skills/ensemble/SKILL.md` מלמד את הסוכן לעבוד נכון: שיווק בעברית,
  הצעת מחיר לפני כל קרדיט, ואישורים שנשארים אצלכם.

## הכלים

| כלי | מה הוא עושה | קרדיטים |
|---|---|---|
| `get_account` | תוכנית, יתרה, הרשאות המפתח, מודלים וקישורים לאפליקציה | לא |
| `quote_generation` | מחיר של תמונה או וידאו | לא |
| `generate_image` | תמונה שיווקית | כן, עם `confirm` |
| `generate_video` | קליפ של 4–8 שניות, גם מתמונה שלכם (`start_image_url`) | כן, עם `confirm` |
| `get_generation` | סטטוס ותוצרים | לא |
| `list_assets` | התמונות והסרטונים המוכנים | לא |
| `get_brain` | העובדות המאושרות של העסק | לא |
| `start_office_brief` | ריצת קמפיין במשרד | כן, עם `confirm` |
| `run_cascade` | מקור אחד לעד 12 פורמטים | כן, עם `confirm` |
| `get_cascade` | התוצאות של מפל | לא |

### שער ההוצאה

כל כלי שמוציא קרדיטים עובד בשני שלבים:

1. **בלי `confirm`:** הכלי מחזיר הצעת מחיר, ושום דבר לא נגבה:
   ```json
   { "status": "quote", "quote": { "credits": 6, "balance": 520, "affordable": true }, "message": "This costs 6 credits…" }
   ```
2. **עם `confirm: true`:** הכלי מבצע ומחזיר `{ "status": "started", "quote": …, "result": … }`.

`max_credits` (אופציונלי) עוצר כל הוצאה מעל התקרה עם `OVER_MAX_CREDITS`. ב-`idempotency_key` אותו מפתח פעמיים
= יצירה אחת וחיוב אחד.

שגיאות חוזרות כתוצאת כלי עם `isError: true` ו-`{ "error": { "code", "message" } }`, באותם קודים כמו ב-REST
(`docs/api.md`).

## התקנה לפי סוכן

### Claude Desktop

`Settings → Developer → Edit Config`, ואז ב-`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ensemble": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<domain>/api/mcp", "--header", "Authorization:${ENSEMBLE_AUTH}"],
      "env": { "ENSEMBLE_AUTH": "Bearer ens_live_…" }
    }
  }
}
```

ה-`${ENSEMBLE_AUTH}` עוקף באג ידוע של רווחים בארגומנטים ב-Windows. הפעילו מחדש את Claude ובקשו:
„כמה קרדיטים יש לי ב-Ensemble?”.

**claude.ai (Connectors):** חיבור בלחיצה דורש OAuth (שלב 2, למטה). Custom connector לא שולח כותרות.

### Claude Code

```bash
claude mcp add --transport http ensemble https://<domain>/api/mcp --header "Authorization: Bearer ens_live_…"
mkdir -p ~/.claude/skills/ensemble && curl -fsSL https://<domain>/skills/ensemble/SKILL.md -o ~/.claude/skills/ensemble/SKILL.md
```

`/mcp` מראה את `ensemble` מחובר.

### Cursor

`Cursor Settings → MCP → Add new MCP server`, או `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "ensemble": { "url": "https://<domain>/api/mcp", "headers": { "Authorization": "Bearer ens_live_…" } } } }
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{ "mcpServers": { "ensemble": { "httpUrl": "https://<domain>/api/mcp", "headers": { "Authorization": "Bearer ens_live_…" } } } }
```

### Manus

בהגדרות של Manus, בחלק של שרתי MCP מותאמים אישית, ייבוא JSON באותו מבנה כמו של Cursor.

### ChatGPT / OpenAI API

בתוך אפליקציית ChatGPT (`Developer mode → Connectors`) החיבור דורש OAuth (שלב 2). היום: דרך ה-Responses API,
עם המפתח בכותרת:

```bash
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "tools": [{ "type": "mcp", "server_label": "ensemble", "server_url": "https://<domain>/api/mcp",
                "headers": { "Authorization": "Bearer ens_live_…" }, "require_approval": "always" }],
    "input": "כמה קרדיטים יש לי ב-Ensemble?"
  }'
```

## בדיקה מהטרמינל

```bash
curl -s https://<domain>/api/mcp \
  -H "Authorization: Bearer $ENSEMBLE_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://<domain>/api/mcp \
  -H "Authorization: Bearer $ENSEMBLE_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'
```

או: `npx @modelcontextprotocol/inspector` עם Transport `Streamable HTTP`, הכתובת והכותרת.

## שלב 2: OAuth 2.1 לחיבור בלחיצה

הדיזיין המלא נמצא ב-`_progress/connect.md` ("OAuth 2.1 design"). בקצרה: Ensemble משמש כשרת הרשאה לפי מפרט
ההרשאה של MCP (Protected Resource Metadata, ‏Authorization Server Metadata, רישום לקוח דינמי, PKCE עם S256,
מסך הסכמה בעברית שנשען על הסשן של Auth.js), מנפיק access token קצר עם scopes של המפתחות, ו-`/api/mcp` מקבל
גם אותו לצד `ens_live_`.