AI / MCP

The AI / MCP tab under Account Settings → System is where workspace administrators configure Landlord MCP access: connection URL, API keys for external AI clients, account-wide tool permissions, per-user overrides, and audit trails. It governs both the operator AI Assistant (/ai-chat) and third-party MCP clients — distinct from tenant-facing ChatBot settings.

First-time workspace setup

Optional after core Getting Started — Recommended Setup Sequence steps 1–15. Pair API keys and domain policies with Landlord MCP client setup and poll AI usage API during month-end review. Hub tab map: Recommended setup order.

Finding your way in this guide

Skim Who can open this tab, then Connection and API keys for external clients. Operators tune scope in Tool permissions and Per-user permissions. Review changes in Permission audit trail and Assistant activity. Full pairing matrix: AI / MCP section cross-reference · Account Settings — Tab cross-reference.

Direct access

Open AI / MCP at platform.vivin.app/settings/mcp. Route reference: Deep Links — Account Settings.

Pair with other Account Settings tabs

Connection and API keys pair with Landlord MCP HTTP setup; Tool permissions mirror what the in-app AI Assistant can call. Tenant-facing automation stays on ChatBot and Emails. Internal LLM spend: AI usage API (landlord_chat). Hub tab matrix: Account Settings — Tab cross-reference.

Who can open this tab

Audience	What they see
Vivin internal (@vivin.app email)	AI / MCP tab is enabled in the Account Settings sidebar (same rollout allowlist as Tools → AI Assistant).
Other management users	Tab appears in the sidebar but is disabled (greyed out) — /settings/mcp does not open the configuration surface until Vivin widens rollout.
Users with account_settings.mcp	Full manager view: Connection, API keys, account tool permissions, per-user overrides, audit trail, and assistant activity (see Users and roles — Role permissions).
Signed-in users without account_settings.mcp	Read-only My permissions card listing effective per-domain access for the signed-in user.

The tab has no separate tab-level permission gate — any user who can open Account Settings may land on AI / MCP when the rollout allowlist permits. Editing account-wide policy still requires account_settings.mcp.

Layout

The manager view stacks these cards top to bottom:

Section	Purpose
Connection	MCP server URL, setup instructions, and copyable client config snippet.
API keys	Generate, list, and revoke keys external clients use as Bearer tokens.
Tool permissions	Account-wide Off / Read-only / Edit mode per domain (area).
Per-user permissions	Pick a teammate — master AI access switch, per-domain overrides, and optional history window.
Permission audit trail	Paginated log of permission changes (lazy-loaded).
Assistant activity	Paginated log of AI Assistant tool calls and held write confirmations (lazy-loaded).

Unsaved changes

When you change Tool permissions or Per-user permissions without saving, a floating bar appears at the bottom of the viewport with Save changes and Cancel. Switching to another Account Settings tab, navigating away from /settings, or closing the shell while the form is dirty opens Unsaved changes — choose Leave to discard or Stay to keep editing. API keys (generate/revoke) and read-only cards (Connection, audit trail, assistant activity) do not participate in this guard.

Connection

The Connection card shows how an external MCP client reaches your workspace:

• MCP connection URL — copyable HTTPS endpoint for streamable MCP traffic (same host the Landlord MCP server exposes at /mcp).
• How to connect — operator-facing instructions from the server (when configured).
• Example MCP client config — JSON snippet with Authorization: Bearer <your key> for paste into Claude Desktop, Cursor, or similar clients.

When the URL is not provisioned for the account, the card shows Connection not available yet with guidance to contact Vivin support.

Connection card capture re-verified 2026-07-27 10:06 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-settings-ai-mcp-screenshots.ts).

Connector OAuth (Claude, ChatGPT)

Hosted MCP connectors (Claude.ai, ChatGPT) can authorize through Vivin's OAuth 2.1 flow on the Core API host instead of pasting an API key. The consent page lists the tool domains the connector will receive — derived from this tab's Tool permissions and the signing-in user's role. Authorization is blocked until at least one domain is enabled for the account.

Operators connecting a connector do not use the API keys card — they complete OAuth in the connector UI. Revoke access by disabling AI access on Per-user permissions or turning domains Off; the next token refresh fails and the connector prompts for sign-in again.

Full protocol details: Landlord MCP — Connector OAuth. HTTP endpoint reference: MCP OAuth.

API keys

API keys authenticate external AI clients (IDE assistants, custom scripts) before they exchange for a management JWT on the MCP server. Use keys when the client config expects a pasted Bearer token — not for Claude.ai / ChatGPT connector OAuth.

1. Click Generate key.
2. Enter a name (for example Claude Desktop) and choose expiration — 30, 90, 180 days, or Never expires.
3. After creation, copy the full key from the amber Key created banner — Vivin shows the secret once; later visits list only the key prefix.
4. Use Revoke (trash icon) on active keys to invalidate them immediately.

Column	Meaning
Name	Operator label for the integration.
Key	Masked prefix after the reveal step.
Created / Last used / Expires	Lifecycle timestamps.
Status	Active, Revoked, or Expired.

Rotate keys after teammate offboarding or client compromise. Refresh Landlord MCP client sessions after revocation.

Tool permissions

Tool permissions set the account default for each domain. The same policy applies to the in-app AI Assistant and external MCP clients.

Mode	Behaviour
Off	No tools in this domain — assistants cannot read or write.
Read-only	Read tools only (listings, bookings, summaries, and similar).
Edit	Read and write tools — selectable in the UI only when the domain already stores Edit; new selections are capped at Read-only while write access rolls out (the segmented control shows a disabled Edit option with helper copy when the account has not been granted write for that domain yet). Existing Edit rows can stay at Edit until you change them.

Expand a domain row to see the read and write tool names. The UI lists snake_case identifiers (same shape Claude uses in-app); Landlord MCP wire names are the kebab-case equivalents (for example get_finance_overview ↔ get-finance-overview).

Domains

Domain	Typical tools (examples)
Bookings	Summaries, calendar overlap checks, create/update when permitted.
Listings	Listing search, pricing tables, availability.
Properties	Property portfolio reads and edits.
Tenants	Tenant directory and profile reads.
Maintenance	Ticket lists and create when Operations allows.
Payments	Payment lists, manual payment-in when Finance allows.
Bills	Utility bill reads and extraction helpers.
Owners	Owner registry for payout context.
Analytics	Portfolio metrics for AI/MCP: get_finance_overview / get-finance-overview, get_revenue_summary / get-revenue-summary (Finance-page income expected + cash collected — not Analytics ADR/RevPAR), plus debt/cost/maintenance closure reads (#3183). Expand the row to see the snake_case chips.

Analytics domain expand capture 2026-07-27 18:06 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL). Staging /mcp/config Analytics Read-only lists get_revenue_summary, get_finance_overview, get_debt_summary, get_maintenance_closure_rate, get_cost_summary.

Walkthrough: Account Settings → AI / MCP → Tool permissions — expand the Analytics domain to reveal Finance-sourced read tools (get_finance_overview, get_revenue_summary, and related).

Effective access is still capped by each user's role permissions in Users and roles — a domain set to Read-only cannot bypass missing Finance or Bookings module rights on the Core API.

Per-user permissions

Managers pick a team member to layer user overrides on top of account policy:

• AI access — master toggle. When Off, domain rows are disabled and the backend blocks AI tools for that user regardless of account defaults.
• Per-domain segmented control — Off, Read-only, or Edit (subject to the same write cap as account policy). Each row shows the Account policy badge, optional Capped by role hint, and an Effective permission pill.
• History window (days) — optional limit on how far back the AI may read that user's data. Leave empty for unlimited.

Click Save changes on the floating bar to persist overrides. Clearing the history field sends null (unlimited).

Permission audit trail

Collapsible Permission audit trail loads on first expand — 10 entries per page with Refresh and pagination. Columns: Date, Changed by, Action (human-readable log line).

Assistant activity

Collapsible Assistant activity lists recent AI Assistant tool executions for the account — Time, Action (executed tools plus items held for confirmation on destructive writes), and Status (ok, failed, or pending states). Lazy-loaded like the audit trail; use Refresh after triaging a support ticket about unexpected assistant behaviour.

Pair with AI Chat and poll landlord_chat on AI usage API for token spend.

Load failures

When the initial MCP settings fetch fails, the tab shows Failed to load AI / MCP settings with Retry. Per-user config, audit trail, and assistant activity cards use the same pattern on their own Retry links. This is distinct from empty API-key or audit states.

See Glossary — Settings and profile load failures.

AI / MCP section cross-reference

Section	Pair with
Connection	Landlord MCP — How it connects, Management session authentication
Connector OAuth	Landlord MCP — Connector OAuth (Claude.ai, ChatGPT PKCE flow), MCP OAuth (HTTP endpoints)
API keys	Landlord MCP, Resetting a Management User Password — Troubleshooting (JWT refresh)
Tool permissions	AI Chat — How answers are produced, Landlord MCP — Finance-sourced portfolio metrics, Automation & AI — WhatsApp Genius
Per-user permissions	Users and roles (account_settings.mcp)
Unsaved changes	Other Account Settings tabs with dirty-form guards (Emails, ChatBot)
Assistant activity	AI usage API, Using in-app support (AI defects)

Related

• Account Settings hub — System section tab map
• ChatBot — Tenant-facing WhatsApp/email automation (not Landlord MCP)
• Landlord MCP — External MCP server concepts and tool catalogue
• Tenant MCP — Booking-scoped tenant automation (separate server)
• AI Chat module — In-app AI Assistant (/ai-chat)
• AI usage API — Internal LLM token ledger (landlord_chat)