Sayweek fejlesztőknek: API és MCP

Claude és ChatGPT (MCP)

A Sayweek távoli MCP-szerver (Streamable HTTP, OAuth 2.1). A címe:

https://app.sayweek.com/api/mcp

• claude.ai: Beállítások → Connectors → „Add custom connector” → illeszd be a címet → Connect → lépj be a Sayweekbe → Engedélyezés.
• ChatGPT: Beállítások → Apps & Connectors → Advanced → Developer mode → Create → a cím, Authentication: OAuth.

Claude Code:

claude mcp add --transport http sayweek https://app.sayweek.com/api/mcp

Eszközök az asszisztensnek

• list_brands – márkák és csatornák
• get_week_plan – a hét idősávjai és posztjai
• get_calendar_context – hol leszel, milyen napod lesz (a naptárból, eseménycímek nélkül)
• list_posts, list_ideas, get_analytics_summary – olvasás
• create_post_draft, update_post, add_idea – piszkozatok és ötletek
• generate_week_drafts, get_generation_job – a Sayweek megírja a hét piszkozatait a márka hangján
• approve_post – valódi ütemezés – csak „approve” jogosultsággal és bekapcsolt jóváhagyással

Hitelesítés

Minden kérés fejléce: Authorization: Bearer <token>. A token lehet API-kulcs (pp_…, Beállítások → Integrációk → Claude & ChatGPT) vagy OAuth access token (sw_at_…, 1 óráig érvényes, frissíthető). A tokeneket csak hash-ként tároljuk; a jelszó visszaállítása visszavonja az asszisztens-kapcsolatokat.

OAuth 2.1: authorization code + PKCE (S256), dinamikus kliensregisztráció (RFC 7591), metaadatok: /.well-known/oauth-authorization-server és /.well-known/oauth-protected-resource.

Jogosultságok (scope)

• read – márkák, csatornák, terv, posztok, ötletek, naptár-összefoglaló, statisztika
• write – piszkozat írása/szerkesztése, ötlet, hét generálása, el nem küldött poszt törlése
• approve – jóváhagyás = valódi ütemezés; a munkatérben is engedélyezni kell, és minden jóváhagyási szabály érvényes

Solo csomagban csak read; Pro, Team és Agency csomagban write és approve is.

Végpontok

Teljes leírás (OpenAPI 3.1): https://app.sayweek.com/api/v1/openapi.json

Példák

curl

# Next week's plan
curl https://app.sayweek.com/api/v1/week?start=2026-10-05 \
  -H "Authorization: Bearer $SAYWEEK_KEY"

# A draft (never published by the API)
curl -X POST https://app.sayweek.com/api/v1/posts \
  -H "Authorization: Bearer $SAYWEEK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-2026-10-06-linkedin" \
  -d '{"channel_id":"<channel id>","date":"2026-10-06","text":"…","hashtags":["#sayweek"]}'

# Let Sayweek write next week (async job)
curl -X POST https://app.sayweek.com/api/v1/generate -H "Authorization: Bearer $SAYWEEK_KEY"
curl https://app.sayweek.com/api/v1/jobs/<job id> -H "Authorization: Bearer $SAYWEEK_KEY"

JavaScript

const api = (path, init = {}) =>
  fetch(`https://app.sayweek.com/api/v1${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.SAYWEEK_KEY}`, "Content-Type": "application/json", ...init.headers },
  }).then(async (r) => {
    const body = await r.json();
    if (!r.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    return body;
  });

const { data: brands } = await api("/brands");
const job = await api("/generate", { method: "POST", body: JSON.stringify({ brand_ids: [brands[0].id] }) });
const status = await api(`/jobs/${job.id}`);
console.log(status.status, status.done, "/", status.total);

Hibák, lapozás, korlátok

Hibaformátum: { "error": { "code", "message", "details" } }. Listák: { data, next_cursor } – a következő oldal: ?cursor=<next_cursor>. Korlátok kliensenként percenként: 120 olvasás, 30 írás, 6 generálás (429 + Retry-After). POST-nál az Idempotency-Key fejléc 24 órán át visszajátssza az első választ.