# Qabbad ChatGPT, Claude jew l-aġent tal-AI tiegħek (MCP)

Guestbud jitkellem il-**Model Context Protocol (MCP)**, l-istandard miftuħ li jużaw l-assistenti tal-AI biex jaħdmu ma' softwer ieħor. Tqabbad l-aġent tal-AI tiegħek mal-kont ta' Guestbud darba. Wara tista' tgħidlu b'lingwa sempliċi x'għandu jagħmel, pereżempju:

- “Wieġeb il-mistoqsijiet il-ġodda dwar il-parkeġġ fiċ-chat ta' Airbnb.”
- “Min jasal għada, u kulħadd għamel il-check-in?”
- “Biddel il-password tal-Wi-Fi ta' Harbour Loft għal SeaBreeze2026.”
- “Agħmel l-email tad-dettalji tal-check-in aktar ħbiberija u żid ir-regola tax-xugamani tal-baħar.”
- “Liema problemi għadhom miftuħa, u x'irrapporta l-mistieden tal-appartament 3?”

L-aġent jaħdem bid-data **tiegħek**, fil-kont **tiegħek**, u biss bil-permessi li tagħtih int.

## X'jista' jagħmel l-aġent tiegħek

| Qasam | X'jista' jagħmel | Permess tar-rwol meħtieġ |
|---|---|---|
| Kont | Jara b'liema kont u rwol huwa kkonnettjat | — |
| Bookings | Jelenka u jfittex bookings, jaqra booking bid-dettalji tal-check-in, l-istatus tal-ħlasijiet u l-istatus tal-kodiċijiet tal-bieb | Bookings: view |
| Chat mal-mistednin | Jaqra l-konverżazzjoni minn Airbnb, Booking.com, Vrbo … u **jibgħat messaġġi lill-mistieden** (permezz ta' Hostaway jew Channex) | Bookings: view / edit |
| Check-in | Jibgħat il-link tal-check-in jew tfakkira bl-email jew iċ-chat; juri l-kodiċijiet tal-bieb kmieni għal check-in bikri miftiehem | Bookings: edit |
| Bookings | Joħloq booking dirett, jeditja n-noti, il-mistednin u l-kuntatt, jikkanċella | Bookings: edit |
| Problemi | Jelenka r-rapporti ta' problemi tal-mistednin, jimmarkahom għaddejjin jew solvuti, iżid noti interni | Bookings: view / edit |
| Pjan tat-tindif | Check-ins u check-outs tal-jiem li ġejjin bil-ħinijiet tal-wasla / tat-tluq u t-titjiriet | Cleaning plan |
| Listings | Jaqra l-gwida sħiħa tal-mistieden; ibiddel sezzjonijiet (Wi-Fi, passi tal-check-in, regoli tad-dar, tips lokali, extras …); jixgħel jew jitfi proprjetà | Properties: view / edit |
| Messaġġi lill-mistednin | Jaqra u jeditja l-messaġġi awtomatiċi u t-templates; jara preview ta' messaġġ mimli b'booking veru | Settings |
| Statistika | Okkupazzjoni, bookings, taxxa tat-turisti, depożiti, early check-in / late check-out u extras mibjugħa | Reports |
| Kull ħaġa oħra | Jaqra kull parti tar-[REST API](/api/docs) (qari biss) | bħall-API |

**Qatt disponibbli għal aġent:** rifużjonijiet, rilaxx jew ġbir tad-depożiti, settings tal-ħlas, utenti u API keys. Dawn jibqgħu f'idejk fid-dashboard.

## Żewġ modi kif tqabbad

| | Login (rakkomandat) | API key |
|---|---|---|
| Għal | ChatGPT, claude.ai, Claude Desktop u l-mowbajl, Claude Code, Cursor | n8n, Make, frameworks tal-aġenti, il-kodiċi tiegħek, servers mingħajr persuna preżenti |
| Kif | Waħħal l-indirizz tas-server fl-app tal-AI, idħol f'Guestbud, agħżel rwol, agħfas **Allow** | Oħloq key f'Guestbud u waħħalha fl-għodda |
| Min | Il-persuna li tidħol (għandha bżonn il-permess li tqabbad apps, ara hawn taħt) | Xi ħadd li jimmaniġġja l-utenti |
| Jintemm | Meta taqtgħu, meta l-persuna titneħħa, tiġi diżattivata, tieħu rwol ieħor jew tibdel il-password, jew wara 60 jum mingħajr ebda użu | Meta tirrevoka l-key |

L-indirizz tas-server tiegħek jidher taħt **Settings → AI agent (MCP)**:

- `https://guestbud.io/mcp`, jew
- id-dominju tiegħek segwit minn `/mcp`, pereżempju `https://stay.example.com/mcp`.

## 1. Agħżel x'jista' jagħmel l-aġent

L-aġent dejjem jaħdem b'**rwol** — eżatt bħal persuna fit-tim tiegħek (ara [Utenti, rwoli u login](/docs/users-roles-and-sign-in)):

- **Staff** — rakkomandat biex iwieġeb lill-mistednin: jaqra l-bookings, jibgħat messaġġi lill-mistednin u links tal-check-in, jieħu ħsieb ir-rapporti ta' problemi, jara l-pjan tat-tindif. Ma jistax ibiddel listings jew settings.
- **Manager** — barra minn hekk jeditja l-listings, it-templates tal-messaġġi u s-settings, u jaqra l-istatistika.
- **Viewer** — qari biss; ma jista' jibgħat xejn.
- **Cleaning** — il-pjan tat-tindif biss.

Ibda b'**Staff**. Bil-login, tagħżel ir-rwol fuq il-paġna ta' Guestbud li tinfetaħ; qatt ma jista' jkun ogħla mir-rwol tiegħek, u qatt Owner.

## 2. Qabbad bil-login (ChatGPT, Claude, Cursor) {#connect-with-sign-in}

Fejn iżżid l-indirizz tas-server (`https://guestbud.io/mcp`) fl-app tal-AI tiegħek:

- **claude.ai, Claude Desktop u l-mowbajl:** **Settings → Connectors → Add custom connector**, waħħal l-indirizz, **Add**, imbagħad **Connect**.
- **ChatGPT:** **Settings → Apps & Connectors**, oħloq connector (developer mode), waħħal l-indirizz, awtentikazzjoni **OAuth**.
- **Claude Code:** ħaddem `claude mcp add --transport http guestbud https://guestbud.io/mcp`, imbagħad ikteb `/mcp` f'Claude Code u agħżel **Authenticate**.
- **Cursor:** **Settings → MCP → Add server** b'`{ "mcpServers": { "guestbud": { "url": "https://guestbud.io/mcp" } } }`, imbagħad **Connect**.

Imbagħad:

1. Fl-app tal-AI tiegħek, żid Guestbud bl-indirizz tas-server tiegħek kif muri hawn fuq u ibda l-konnessjoni.
2. Tinfetaħ paġna ta' Guestbud. Idħol bil-login normali tiegħek ta' Guestbud (fuq guestbud.io iddaħħal ukoll l-isem qasir tal-kumpanija tiegħek).
3. Iċċekkja l-isem tal-app u fejn terġa' lura (pereżempju *claude.ai*), agħżel ir-**rwol** għall-app u agħfas **Allow**.
4. Lura fl-app tal-AI, l-għodod ta' Guestbud ikunu disponibbli. Staqsi, pereżempju, “Liema mistednin jaslu din il-ġimgħa?”.

**Tibqa' kkonnettjata:** l-app iġġedded l-aċċess tagħha awtomatikament fl-isfond (kull siegħa). M'għandekx bżonn terġa' tqabbad sakemm l-aġent jintuża mill-inqas darba kull 60 jum.

**Min jista' jqabbad:** taħt **Settings → AI agent (MCP) → Who may connect AI apps with sign-in** tagħżel *Team members who manage users* (default), *All team members* (kull wieħed sar-rwol tiegħu) jew *Nobody*. Meta taqleb għal *Nobody*, il-konnessjonijiet kollha bil-login jieqfu f'daqqa.

**Apps ikkonnettjati:** l-istess paġna telenka kull app ikkonnettjata bil-persuna li daħlet, ir-rwol tagħha u meta ntużat l-aħħar. **Disconnect** iwaqqafha minnufih.

## 3. Qabbad b'API key (għodod tal-awtomazzjoni u l-kodiċi tiegħek) {#connect-with-an-api-key}

Uża key għal għodod li jaħdmu mingħajr ma xi ħadd jidħol: n8n, Make, frameworks tal-aġenti, scripts u servers.

1. Iftaħ **Settings → AI agent (MCP)** u espandi **For automation tools and your own code (API key)** (għandek bżonn il-permess li timmaniġġja l-utenti).
2. Daħħal **Name**, pereżempju *n8n — tweġibiet lill-mistednin*, u agħżel ir-**Role**.
3. Agħfas **Create key and show the setup**.
4. Il-key sħiħa (`gpk_…`) tintwera **darba biss**, flimkien ma' linji tas-setup lesti li diġà fihom il-key. Ikkopjahom issa. Jekk titlef il-key, irrevokaha u oħloq oħra ġdida.

Key taħdem biss għall-kont tiegħek. Tiġi rrifjutata fuq id-dominju ta' kumpanija oħra.

### n8n u għodod oħra tal-awtomazzjoni

F'n8n, żid **AI Agent** bil-**MCP Client Tool**:

- **Endpoint**: `https://guestbud.io/mcp`
- **Server transport**: *HTTP Streamable*
- **Authentication**: *Bearer Auth*, token = il-key `gpk_…` tiegħek

Kull klijent MCP ieħor li jista' jibgħat header jaħdem bl-istess mod:

- URL: `https://guestbud.io/mcp`
- Transport: *Streamable HTTP*
- Header: `Authorization: Bearer gpk_…`

### Claude Code, Claude Desktop, Cursor, Windsurf b'key

Għal dawn l-apps aħjar tuża l-login. Jekk xorta trid key (pereżempju fuq server):

```
claude mcp add --transport http guestbud https://guestbud.io/mcp --header "Authorization: Bearer gpk_…"
```

L-apps li jibdew servers MCP minn file tal-konfigurazzjoni jużaw il-bridge b'xejn **mcp-remote** (jeħtieġ [Node.js](https://nodejs.org)):

```
{
  "mcpServers": {
    "guestbud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://guestbud.io/mcp", "--header", "Authorization:${GUESTBUD_AUTH}"],
      "env": { "GUESTBUD_AUTH": "Bearer gpk_…" }
    }
  }
}
```

Il-key qiegħda fil-parti `env` apposta: hekk jiġu evitati problemi bl-ispazji fuq Windows.

## 4. Użah

Staqsi b'lingwa sempliċi, kif tistaqsi lil kollega. Xi eżempji li jaħdmu tajjeb:

- **Chat mal-mistednin:** “Ħares lejn il-bookings li jaslu fit-tlett ijiem li ġejjin. Aqra l-konverżazzjonijiet tagħhom fuq Airbnb u Booking.com u ikteb abbozzi ta' tweġibiet għall-mistoqsijiet li għadhom bla tweġiba. Urihomli qabel tibgħathom.”
- **Segwitu tal-check-in:** “Min jasal għada u għadu ma għamilx il-check-in online? Ibgħatilhom tfakkira permezz taċ-chat tal-booking.”
- **Check-in bikri:** “Il-mistieden tal-booking GP-7KQ2XD jista' jagħmel check-in fit-12:00 — iftaħ il-kodiċijiet kmieni u għidlu fiċ-chat.”
- **Listings:** “Urini l-passi tal-check-in ta' Capua Flats u kkoreġi l-kodiċi tal-lift għal 3044.”
- **Problemi:** “Elenka l-problemi miftuħa; immarka dik tal-Wi-Fi f'Harbour Loft bħala solvuta bin-nota ‘router reġa' nbeda’.”
- **Tindif:** “X'għandu jagħmel it-tim tat-tindif nhar is-Sibt, skont il-ħin tat-tluq? Immarka t-turnovers tal-istess jum.”
- **Messaġġi:** “Erġa' ikteb l-email tad-dettalji tal-check-in b'ton aktar sħun, żomm il-placeholders kollha u urini preview bil-booking li jmiss.”
- **Numri:** “Kemm-il late check-out biegħna x-xahar li għadda, u liema extras inbiegħu l-aktar?”

**Tip:** ħalli lill-aġent jikteb abbozz tal-messaġġi lill-mistednin l-ewwel u jurihomlok (“urihomli qabel tibgħathom”). Meta tafdah, tista' tħallih jibgħat direttament.

## Sigurtà

- **Inti tagħżel il-permessi:** ir-rwol tal-key jew tal-login jiddeċiedi kollox. L-aġent jara biss l-għodod li jippermetti r-rwol tiegħu, u s-server jerġa' jiċċekkja kull sejħa.
- **L-ebda flus ma jiċċaqalqu:** ir-rifużjonijiet, id-depożiti, is-settings tal-ħlas, l-utenti u l-keys ma jintlaħqux permezz tal-MCP.
- **Test tal-mistednin mhux fdat:** il-mistednin jistgħu jiktbu kollox f'chat jew f'formola tal-check-in. Guestbud jgħid lill-aġent biex jittratta kull ma kiteb mistieden bħala informazzjoni, qatt bħala struzzjoni. Jgħidlu wkoll biex ma jibgħatx kodiċijiet tal-bieb qabel ma l-booking jurihom bħala viżibbli. Xorta waħda, iċċekkja x'jibgħat l-aġent, speċjalment fil-bidu.
- **Kull bidla tiġi rreġistrata:** kull azzjoni li tbiddel xi ħaġa (messaġġ mibgħut, booking jew listing mibdul, kodiċi miftuħ …) tidher f'**Settings → Audit trail** taħt l-isem tal-app jew tal-key. Il-konsultazzjonijiet sempliċi ma jidhrux, biex it-trail jibqa' faċli biex jinqara.
- **Inqas data personali:** l-aġent jieħu dak li għandu bżonn biex jgħin lill-mistednin, mhux aktar. Id-dettalji tal-booking ma jinkludux id-data tad-dokument tal-identità u l-uploads, l-indirizzi IP u l-kodiċi tas-smart lock tal-booking. L-aċċess għall-API għall-qari biss jeskludi files, utenti, API keys, l-audit trail, webhooks, data tar-reġistrazzjoni tal-mistednin u s-settings tal-ħlas, tal-email u tas-serraturi.
- **Limiti:** mhux aktar minn 120 sejħa ta' għodda kull minuta u 40 messaġġ lill-mistednin kull siegħa għal kull konnessjoni jew key; mhux aktar minn 10 talbiet f'batch wieħed, u tweġibiet twal ħafna jitqassru.
- **Login sigur:** Guestbud juża l-istandard għal-login tal-apps tal-AI (OAuth 2.1 b'PKCE). L-app qatt ma tara l-password tiegħek; tirċievi token tal-aċċess validu għal siegħa u token tat-tiġdid li jinbidel ma' kull użu. Jekk token tat-tiġdid qatt jintuża darbtejn, Guestbud jagħlaq il-konnessjoni. Token tal-login jaħdem biss għall-konnessjoni tal-aġent tal-AI, mhux għall-bqija tal-API.
- **Irrevoka meta trid:** **Settings → AI agent (MCP)** → **Disconnect** (login) jew **Revoke** (key). L-aġent jitlef l-aċċess minnufih.
- **Il-fornitur tal-AI tiegħek:** id-data li jaqra l-aġent tiġi pproċessata mis-servizz tal-AI li tqabbad (pereżempju Anthropic għal Claude). Iċċekkja li dan jaqbel mal-avviż tal-privatezza tiegħek għall-mistednin.

## Mistoqsijiet frekwenti

### Liema aġenti tal-AI jaħdmu ma' Guestbud?

Kull klijent MCP. ChatGPT, claude.ai, Claude Desktop u l-mowbajl, Claude Code u Cursor jqabbdu bil-login. n8n, il-frameworks tal-aġenti u l-kodiċi tiegħek iqabbdu b'API key.

### Kemm iddum konnessjoni bil-login?

Sakemm tużaha. L-app iġġedded l-aċċess tagħha awtomatikament kull siegħa; il-konnessjoni tintemm biss wara 60 jum mingħajr ebda użu, meta taqtagħha, jew meta l-persuna li daħlet titneħħa, tiġi diżattivata, tieħu rwol ieħor jew tibdel il-password.

### L-aġent jista' jibgħat il-kodiċijiet tal-bieb lill-mistednin?

Biss jekk ir-rwol tiegħu jista' jaqra l-bookings u l-listings, u biss meta l-booking tal-mistieden juri l-kodiċijiet bħala viżibbli: il-check-in u l-ħlasijiet lesti, u wasal il-ħin tal-check-in (jew infetħu kmieni minnek). L-aġent jaf b'din ir-regola. It-templates tal-messaġġi tiegħek b'`{doorCodes}` isegwu l-istess regola awtomatikament.

### Diversi aġenti jistgħu jużaw Guestbud fl-istess ħin?

Iva. Kull login u kull key huwa konnessjoni separata bir-rwol tagħha, elenkata separatament fl-audit trail, u tista' taqta' waħda mingħajr ma taffettwa lill-oħrajn.

### L-aġent jiswa xi ħaġa f'Guestbud?

Le. L-aċċess għall-MCP huwa parti mill-kont tiegħek. L-aġent innifsu jiċċarġjak għalih il-fornitur tal-AI tiegħek.

### Hemm ukoll API għall-iżviluppaturi?

Iva — l-aġent juża l-istess permessi tar-[REST API](/api/docs) u tal-[webhooks](/docs/webhooks); ara l-[quick start tal-API](/docs/api-quickstart).