# Tools · Visitors

> MCP tools for the Visitors module (coworking): register, list, read, edit and cancel guests, today's expected guests, finding the host and marking or undoing the arrival at the front desk.

The [Visitors](/espacos/visitantes) module through the assistant: registering the guest ahead of time, editing and canceling, seeing who is expected today at the front desk and marking the arrival with a notice to the host. The guest kiosk is an iPad screen; the assistant does **not** run it.

Each tool carries a badge: <span class="tool-kind tool-kind-read">Read-only</span> changes nothing, <span class="tool-kind tool-kind-write">Changes</span> creates or changes something right away, and <span class="tool-kind tool-kind-confirm">Asks to confirm</span> only acts after your yes to a summary. See [Money and confirmation](/mcp/dinheiro-e-confirmacao).

## In short

| Tool | What it does | Minimum role | Type |
|---|---|---|---|
| [`create_visitor_invitation`](#create-visitor-invitation) | Registers a guest | Any with access to the space (the settings can restrict); team, on behalf of another host | <span class="tool-kind tool-kind-write">Changes</span> |
| [`list_visitor_invitations`](#list-visitor-invitations) | Lists and searches guests | Any (a member sees their own) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_visitor_invitation`](#get-visitor-invitation) | One registration | Owner of the registration or team | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`update_visitor_invitation`](#update-visitor-invitation) | Edits before the arrival | Owner of the registration or team | <span class="tool-kind tool-kind-write">Changes</span> |
| [`cancel_visitor_invitation`](#cancel-visitor-invitation) | Cancels a registration | Owner of the registration or team | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`list_visitors_today`](#list-visitors-today) | Today's expected and arrived guests | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`search_visitor_hosts`](#search-visitor-hosts) | Finds the host | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`mark_visitor_arrived`](#mark-visitor-arrived) | Marks the arrival | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |
| [`undo_visitor_arrival`](#undo-visitor-arrival) | Undoes an arrival | Moderator or finance | <span class="tool-kind tool-kind-write">Changes</span> |

The roles are those of the routes: the assistant never does more than the connected person would do on screen. The team, here, is the owner, the admin, the moderator and finance; the moderator and finance handle **only today's guests**. The space is created with [`create_space`](/mcp/ferramentas-comunidade#create-space) and `module: "visitors"`; [`update_space`](/mcp/ferramentas-comunidade#update-space) changes only what you send.

## The space settings

The `visitors` argument of `create_space` and `update_space` accepts:

| Field | Type | Description |
|---|---|---|
| `attendance_space_id` | id | The [Attendance](/mcp/ferramentas-presenca) space where arrivals are recorded. Required on creation (`list_spaces`) |
| `who_can_invite` | `members`, `staff` or `group` | Who registers: any member with access, only the team, or the group in `inviter_group_id` plus the team |
| `inviter_group_id` | id or `null` | The group of whoever registers (`list_groups`); required with `group` |
| `fields` | `{company, email, phone}`, each `off`, `optional` or `required` | What the form asks about the guest |
| `notify_host_on_register` | true or false | Confirms the registration to the host by email (default: yes) |
| `email_guest` | `off`, `optional` or `always` | The [email to the guest](/espacos/visitantes#email-to-the-guest) (default: `off`) |
| `arrival_instructions` | text up to 500 characters, or `null` | Where to go and who to ask for |
| `max_expected_per_host_per_day` | 1 to 1000, or `null` | Limit of guests per host per day |

## `create_visitor_invitation`

<span class="tool-kind tool-kind-write">Changes</span>

**Register a guest.** It doesn't create an account for the guest. Whoever the settings allow registers for themselves; the team passes `host_profile_id` to register on behalf of someone else. Company, email and phone follow the settings (a turned-off field is ignored; a missing required one is refused). The host may receive a confirmation email and the guest another, depending on `notify_guest` and the settings; the assistant tells the person. This is a third party's personal data. *Role: any with access to the space.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | The Visitors space |
| `guest_name` | text | Yes | Up to 100 characters |
| `expected_date` | `YYYY-MM-DD` | Yes | In the community time zone; can't be in the past |
| `start_time` | `HH:mm` | Yes | Start time, in the community time zone |
| `end_time` | `HH:mm` | No | After the start |
| `guest_company`, `guest_email`, `guest_phone` | text | Per the settings | |
| `notify_guest` | true or false | No | Notifies the guest by email; only works with an email and per `email_guest` |
| `host_profile_id` | id | No | Team only: the host (`search_visitor_hosts`). Without it, it's you |

**Ask like this:** *"Register Maria Souza (maria@memberfy.net) as my guest tomorrow, from 2 pm to 3 pm."*

## `list_visitor_invitations`

<span class="tool-kind tool-kind-read">Read-only</span>

**List the guests.** By expected time. A member sees only their own (as host or as whoever registered), for any date; moderator and finance also see all of today's; admin and owner see any date. Each item says what you can do (`canEdit`, `canCancel`, `canArrive`, `canUndoArrival`). *Role: any with access to the space.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | |
| `status` | `EXPECTED`, `ARRIVED`, `CANCELED` or `NO_SHOW` | No | `EXPECTED` covers today onward; `NO_SHOW` is expected for a day that has passed |
| `from`, `to` | `YYYY-MM-DD` | No | Period, inclusive, in the community time zone |
| `q` | text | No | Part of the name or company |
| `page`, `limit` | numbers | No | Pagination (up to 100) |

**Ask like this:** *"Which guests do I have registered for this week?"*

## `get_visitor_invitation`

<span class="tool-kind tool-kind-read">Read-only</span>

**One registration.** The host and whoever registered read their own; the team reads today's; owner and admin, any. Another registration, another community or an unknown id: `404`. *Role: any.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | From `list_visitor_invitations` or `list_visitors_today` |

## `update_visitor_invitation`

<span class="tool-kind tool-kind-write">Changes</span>

**Edit before the arrival.** After the arrival, or once canceled, the answer is `409`. Send only what changes; `host_profile_id` is for the team. Changing the day, the time or the host sends a new confirmation to the host, once per change. The registration's owner and the team edit (moderator and finance, today's only). *Role: any, depending on who can edit.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | |
| `guest_name`, `guest_company`, `guest_email`, `guest_phone` | text | No | |
| `expected_date`, `start_time`, `end_time` | date and times | No | Same formats as `create_visitor_invitation` |
| `notify_guest` | true or false | No | |
| `host_profile_id` | id | No | Team only |

**Ask like this:** *"Change Maria's visit to 3 pm."*

## `cancel_visitor_invitation`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Cancel a registration.** It becomes **Canceled**; nothing is deleted. Whoever registered, the host or the team (moderator and finance, today's only). Already canceled: nothing changes. Already arrived: `409`, undo the arrival first. *Role: any, depending on who can cancel.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | |

**Returns:** on the first call, the summary (guest, host, day and time) and the confirmation code.

## `list_visitors_today`

<span class="tool-kind tool-kind-read">Read-only</span>

**The front desk view.** Today's expected and arrived guests (community time zone), from all hosts, with the counts. Canceled and "did not show up" don't appear. `alreadyMember` indicates the guest's email belongs to a member. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | |
| `q` | text | No | Name or company, ignoring accents and case |

**Ask like this:** *"Who am I expecting today at the front desk?"*

## `search_visitor_hosts`

<span class="tool-kind tool-kind-read">Read-only</span>

**Find the host.** Members of the space whose name (or a word of it) starts with `q`, with 3 letters or more. It returns only id, name, photo and initials; the id is the `host_profile_id` for `create_visitor_invitation`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `space` | id or link | Yes | |
| `q` | text | Yes | From 3 to 100 characters |

## `mark_visitor_arrived`

<span class="tool-kind tool-kind-write">Changes</span>

**Mark the arrival.** It creates the visit in the linked Attendance space (front desk method, with the registration's name) or links the one the team had already recorded. The host is notified by email when Attendance is set up for it; `hostNotified` says whether the notice went to the queue, and the assistant tells the person. It's idempotent: the second call returns `alreadyArrived: true`. Only on the registration's day (another day: `409`); outside the time window is fine; canceled: `409`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | From `list_visitors_today` |

**Returns:** `invitation`, `visit`, `hostNotified` and `alreadyArrived`.

**Ask like this:** *"Maria Souza has arrived."*

## `undo_visitor_arrival`

<span class="tool-kind tool-kind-write">Changes</span>

**Undo an arrival marked by mistake.** On the same day and before the guest's departure. The visit leaves the lists and the occupancy (it stays in Attendance's record) and the registration goes back to **Expected**. No arrival, another day or already left: `409`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | |

## Related

- [Visitors](/espacos/visitantes)
- [Tools: Attendance](/mcp/ferramentas-presenca)
- [Tools](/mcp/ferramentas)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)
- [Recipes](/mcp/receitas)