Tenant MCP (AI integrations)

First-time workspace setup

Optional after setup steps 10–11 (Tenant categories, Emails) and Tenant Portal — booking-scoped tools need a live reservation from step 14 Bookings. Chatbot rules: ChatBot. Concept pairing: Concepts — Setup sequence after go-live.

Finding your way in this guide

Skim What you can do with it and How it connects, then the Tool overview table. Safety boundaries: Permissions and safety. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Tenant MCP section cross-reference · Concepts — Concept cross-reference.

VIVIN ships a Tenant Model Context Protocol (MCP) server (apps/tenant-mcp-server in the monorepo) that lets compatible AI clients call typed tools against tenant booking context using the same Core API backing as the management platform. It is aimed at tenant-facing automation — chatbots, assistants, and integrations that answer questions or take actions for a specific booking (identified by tenant email, phone, and/or booking ID), not for whole-portfolio administration.

Pair with other concepts

Contrast account-wide tools in Landlord MCP; portal links and booking context mirror Tenant Portal (including portal access by tenant category); channel routing and chatbot rules sit in Automation & AI. Landlord-side LLM cost for in-app AI Chat and utility extraction is on AI usage API — tenant MCP tool calls are not metered on that ledger. Topic-to-tool pairing: Tenant MCP section cross-reference. Full pairing matrix: Concepts — Concept cross-reference.

This page is a high-level operator guide. Exact request and response shapes follow the Core API (see API Reference); enable Core Swagger on your API host when you need field-level detail (ENABLE_CORE_API_SWAGGER in Core API environment — see repository AGENTS.md).

Account-scoped MCP

For portfolio-wide tools (properties, listings, bookings, vacancy and calendar-style reads), use the Landlord MCP server (apps/landlord-mcp-server). The tenant server is booking- and tenant-context scoped and targets automation that already knows which tenant or booking the conversation is about.

What you can do with it

Pair with other Tenant MCP sections

Booking-scoped automation pairs with Tenant Portal, Inbox WhatsApp threads, and Automation & AI — AI Tenant Support Chatbot. Contrast account-wide reads in Landlord MCP. Full pairing matrix: Tenant MCP section cross-reference.

Typical use cases:

Power a tenant support assistant that reads booking dates, payment status, contract snippets, portal links, and maintenance history.
Load landlord-configured chatbot rules and persona (IF/THEN guidance and tone from Management → Account settings → ChatBot) so external AI replies stay on-brand and policy-aligned.
List bookings for an email or phone when a tenant may have more than one active reservation, then narrow follow-up tool calls to the chosen bookingId.
Create maintenance tickets (with optional attachments from public URLs) or notify the landlord through the same flows the product uses — by booking ID when known, or by phone (and optional email) when the tenant is not yet matched to a reservation.

Every tool resolves to Core API routes: 403 or validation errors from the API surface in the MCP response like any other client.

Full pairing matrix: Tenant MCP section cross-reference.

How it connects

Pair with other Tenant MCP sections

Session bootstrap pairs with Management session authentication, Resetting a Management User Password (refresh Bearer JWT + Mcp-Session-Id), and Automation & AI — External AI clients. Full pairing matrix: Tenant MCP section cross-reference.

Topic	Detail
Protocol	Model Context Protocol over HTTP (streamable transport).
Base URL	Configured per deployment; locally often `http://localhost:8000` (default `PORT` in server env).
MCP path	Streamable HTTP traffic is served at `/mcp` on that host (for example `http://localhost:8000/mcp`). Point MCP clients at this URL path.
Core API	`API_BASE_URL` must point at your VIVIN Core API (required).
Auth	Bearer token (JWT) for session creation; sessions reuse `Mcp-Session-Id` like other MCP HTTP servers in the repo.

Environment validation lives in apps/tenant-mcp-server/src/env.validation.ts (PORT, API_BASE_URL, optional DISCORD_LOGGER_WEBHOOK). Session behaviour matches the landlord server: Mcp-Session-Id on follow-up requests after an authenticated session is created.

Full pairing matrix: Tenant MCP section cross-reference.

Request path

flowchart LR
  subgraph clientSide[Your environment]
    C[MCP client\nchatbot or tenant bridge]
  end
  subgraph vivinSide[VIVIN services]
    T[Tenant MCP server\nHTTP streamable /mcp]
    A[Core API\nbooking- and tenant-scoped routes]
  end
  C -->|Bearer JWT + session headers| T
  T -->|API_BASE_URL\ntools resolve tenant/booking context| A

Identifiers such as email, phone, or bookingId in tool arguments tell the server which reservation the automation is acting on; portfolio-wide admin tasks stay on Landlord MCP.

From MCP tools to HTTP

Pair with other Tenant MCP sections

Swagger and inbound webhooks pair with API Reference hub, Webhooks & Notifications, and Integrations & Distribution (channel POSTs are HTTP — not MCP tools). Full pairing matrix: Tenant MCP section cross-reference.

Tenant tools resolve to Core API routes behind booking and tenant context. For OpenAPI shapes and status codes, use Integration Swagger on your API host (see API Reference); enable Core Swagger when you need routes that are not exposed on the integration surface.

Integration Swagger UI — listings operations expanded with Try it out

Inbound partner webhooks (channels → Vivin)

Tenant MCP answers booking-scoped questions for external assistants; marketplace partners still deliver paid/cancelled events through inbound Core API webhooks (for example Housing Anywhere and Uniplaces). Wire those callbacks using Integration Swagger on your API host — see Webhooks & Notifications.

Integration Swagger — Housing Anywhere POST webhook expanded with path parameter and request body schema

Integration Swagger — Uniplaces POST webhook expanded with landlordKey path parameter and request body schema

Full pairing matrix: Tenant MCP section cross-reference.

Tool overview

Pair with other Tenant MCP sections

Write tools mirror tenant-facing flows — pair create-maintenance-ticket with Operations > Tickets, get-payment-info with Handling a Late Payment — Step 3, and get-chatbot-rules with Settings > Chatbot. Full pairing matrix: Tenant MCP section cross-reference.

Tools are registered in apps/tenant-mcp-server/src/server.ts. Names below are the MCP tool identifiers (kebab-case). A typical build exposes 18 tools from that file; if you fork or gate tools, re-count in source rather than relying on this number alone.

Booking and contract data

Tool	Purpose
`list-bookings-by-email`	List active bookings for a tenant by email or phone (use first when multiple bookings are possible).
`request-booking-data`	Aggregate booking payload for a tenant (email/phone/booking context per tool schema).
`request-contract-data`	Contract-oriented data for a tenant.
`get-booking-status`	Status and requirement-style information for the booking.
`get-dates-and-schedule`	Check-in/out and schedule-related fields.
`get-listing-calendar`	Calendar for the tenant’s unit (identifiers per tool schema).

Property, payments, and portal

Tool	Purpose
`get-property-and-location`	Property and location details for the booking context.
`get-payment-info`	Payment schedule and related information.
`get-security-deposit-info`	Deposit terms and amounts where exposed.
`get-tenant-info`	Tenant profile and billing-related fields.
`get-portal-links`	Tenant portal URLs for the booking.

Chatbot configuration (read-only)

Tool	Purpose
`get-chatbot-rules`	Landlord IF / THEN virtual assistant rules (same source as Management → Account settings → ChatBot). Returns plain text for use in prompts.
`get-chatbot-persona`	Persona text (tone, role, boundaries); empty when unset.

Call these early when the assistant must follow account-specific policies or voice alongside booking facts.

Maintenance and escalation

Tool	Purpose
`get-maintenance-tickets`	Tickets associated with the tenant/booking.
`create-maintenance-ticket`	Open a ticket (title, description, category; optional priority, responsible property manager, attachment URLs downloaded server-side).
`list-property-managers`	Discover assignable property manager IDs (for `responsibleId` on create).
`notify-landlord`	Send a notification to the landlord for a known `bookingId` (write; treat as operator-visible).
`notifylandlord-number`	Notify the landlord when the tenant is identified by phone (required) and optional email, but no booking ID is available yet — for example before `list-bookings-by-email` resolves a reservation. Prefer `notify-landlord` whenever you already have a valid booking ID.

Write tools

notify-landlord, notifylandlord-number, and create-maintenance-ticket change operational state or notify your team. Use least-privilege tokens, test on non-production workspaces first, and ensure only intended automations can invoke them.

Full pairing matrix: Tenant MCP section cross-reference.

Permissions and safety

Pair with other Tenant MCP sections

JWT scope and portal gates pair with Users and roles, Settings > Tenant categories (portal module toggles get-portal-links may surface), and scope contrast in Landlord MCP. Full pairing matrix: Tenant MCP section cross-reference.

Access is bounded by the authenticated token and Core API rules — the same permission model that protects tenant-facing integrations.
Prefer listing bookings first when identity is ambiguous (list-bookings-by-email), so follow-up calls use the correct bookingId.
Attachment URLs on create-maintenance-ticket must be publicly downloadable http/https links the server can fetch; limits apply (see tool description in code).

Full pairing matrix: Tenant MCP section cross-reference.

Tenant MCP section cross-reference

Use this table when one Tenant MCP topic naturally leads into portal UX, chatbot configuration, or a module tab — each row links to the docs you should read before or after wiring a booking-scoped external client.

| Tenant MCP topic | Pair with these docs | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What you can do with it | Tenant Portal, Automation & AI — AI Tenant Support Chatbot, Inbox module | | How it connects | Management session authentication, Landlord MCP (scope contrast; refresh Bearer JWT after management password rotation — Resetting a Management User Password — Step 3), Automation & AI — External AI clients, Resetting a Management User Password (management email/password contrast — tenant MCP Bearer JWT does not replace platform sign-in; get-portal-links / get-payment-info remain available while operators reset management credentials; notify-landlord does not fix operator JWT scope — Troubleshooting) | | From MCP tools to HTTP | API Reference hub, Webhooks & notifications | | Booking and contract data tools | Bookings module, Booking Lifecycle, Processing a New Booking — Step 1 (list-bookings-by-email), Processing a New Booking — Step 6 (get-booking-status), Onboarding a New Property — Step 5 (list-bookings-by-email after first channel import), Managing a Check-in — Step 1 (get-dates-and-schedule), Managing a Check-in — Step 5 (get-booking-status), Managing a Check-out — Step 1 (get-dates-and-schedule, list-bookings-by-email), Managing a Check-out — Step 7 (get-booking-status), Cancelling a Booking — Step 1 (request-contract-data, get-dates-and-schedule), Cancelling a Booking — Step 4 (get-booking-status), Cancelling a Booking — Step 5 (get-listing-calendar), Manual block hygiene (get-listing-calendar when tenants ask about blocked dates; Step 3 / Steps 4–5 list-bookings-by-email, request-booking-data, notify-landlord; contrast Landlord MCP portfolio reads in Step 5) | | Property, payments, and portal tools | Tenant Portal — Payments and documents, Tenant Portal — Utilities tab, Tenant Portal — Portal access by tenant category, Payment Allocation, Finance — Transactions, Finance — Issuing credit notes, Settings > Tenant categories, Notifications — Payment overdue alerts, Notification triage — Step 4 (get-payment-info, get-tenant-info, list-bookings-by-email when Inbox threads preceded payment alerts), Notification triage — Step 5 (get-payment-info before bulk Mark all as read), Processing a New Booking — Step 3 (get-payment-info for tenant-facing confirmation balances), Processing a New Booking — Step 5b (get-payment-info while receipts stay pending), Handling a Late Payment — Step 1, Managing a Check-in — Step 3 (get-payment-info), Managing a Check-in — Step 3b (get-payment-info while receipts stay pending), Managing a Check-in — Step 4 (get-portal-links, get-dates-and-schedule), Managing a Check-out — Step 1 / Step 5 (get-security-deposit-info), Managing a Check-out — Step 4 / Step 6 (get-payment-info), Managing a Check-out — Step 6b (get-payment-info while receipts stay pending), Cancelling a Booking — Step 1 (get-payment-info; contrast with operator Cancel booking in Step 4), Cancelling a Booking — Step 2 / Step 3, Entering Monthly Utility Bills — Step 4 (get-payment-info, notify-landlord), Entering Monthly Utility Bills — Step 4b (get-payment-info while overage receipts stay pending), Portfolio KPI review — Step 6 (get-tenant-info, get-payment-info; list-bookings-by-email when segment review started from a tenant message), Portfolio KPI review — Step 7, Glossary — Tenant category | | Chatbot configuration (read-only) | Settings > Chatbot, Bookings — Communication tab, Settings > Emails, Settings > Tenant categories (Communications / Email toggle per segment), Onboarding a New Property — Step 4 / Step 7 (chatbot and segment setup before first reservation), Glossary — Tenant category | | Maintenance and escalation | Operations > Tickets, Managing a Check-in — Step 2 (get-maintenance-tickets, create-maintenance-ticket), Managing a Check-in — Step 3 (notify-landlord), Managing a Check-out — Step 2 / Step 3 (get-maintenance-tickets, create-maintenance-ticket), Managing a Check-out — Step 4 / Step 6 (notify-landlord), Cancelling a Booking — Step 3 / Step 4 (notify-landlord), Cancelling a Booking — Step 6 (get-maintenance-tickets), Handling a Late Payment — Step 6 (notify-landlord tenant-facing alert — contrast with operator segment filters and Landlord MCP portfolio reads), Notification triage — Step 4 / Step 5 (notify-landlord before Mark all as read on tenant-channel escalations), Manual block hygiene (notify-landlord when external assistants escalate unclear calendar holds — does not clear operator manual rows; Step 3 during Audit scan), Using in-app support (Vivin product tickets when MCP needs credential or scope changes — contrast create-maintenance-ticket / notify-landlord) | | Permissions and safety | Users and roles, Landlord MCP — Permissions, Settings > Tenant categories (portal module gates get-portal-links may surface), Glossary — Tenant category | | Lockout catch-up after password recovery | Sign-in restored; concept validation backlog accumulated | Common Workflows — Lockout catch-up, Getting Started — Lockout catch-up, Resetting a Management User Password — Step 3 | | Pending manual receipt approval | Recorded bank transfers still pending until Approve payments | Common Workflows — Pending manual receipt approval, Finance — Pending manual payments, FAQ — Manual receipt still pending | | Reject/revert mistaken receipts | Duplicate or wrong-booking receipts after Approve | Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, Glossary — Credit note (payment reject/revert) | | Portfolio segmentation by tenant category | Review one tenant segment across modules | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Finance — Tenant category filter, Tenants — Tenant category filter | | Notification row-click navigation | Booking-scoped MCP after alert row-click | Concepts — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | get-payment-info vs receivables triage | Concepts — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Upcoming booking MCP context | Concepts — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b |