# Connect your agent to Property Bot

Use your existing housing profile from a call or WhatsApp conversation. Your agent should read saved preferences before asking you to repeat them.

## Connect

Use your client's remote MCP connection to `https://mcp.property.bot/mcp` and complete its OAuth sign-in. For clients that can follow HTTP instructions, start at https://property.bot/auth.md. That URL serves the WorkOS-generated registration guide only when Agent Registration is enabled; otherwise it describes the existing OAuth route. Follow the published instructions, not guessed endpoints.

After authentication, call `connection_status`.

- `phone_linked: true`: skip verification. Call `lookup_person` if allowed, read the existing profile, and ask only for missing or changed preferences.
- `phone_linked: false`: ask for the number the user called or messaged from. Call `start_phone_verification`, explain the returned delivery channel, and ask for the six-digit code. Call `confirm_phone_verification`, then `lookup_person`. Never infer ownership from a supplied number. Verification currently supports +1 numbers only.
- New user: verify their current number, read the profile, then collect the missing city, housing need and budget. Save only user-provided facts with `remember_person`.

WorkOS sign-in/claim and phone verification are different steps with different codes. Never send a phone code to a WorkOS claim endpoint. Users who called without creating a WorkOS account may need to sign up through their MCP client's OAuth flow first. Do not send room seekers to the operator login.

## Search

Use `remember_person` to update preferences only when the user asks and the agent has `profile:write`. Use `find_matches` for a shortlist. Match cards contain limited summaries; they are not a directory of people's contact details. If there are no results, explain that plainly and discuss changes to the search. An empty profile needs a housing need before it can match.

No tool schedules background searches. `send_text` sends a real SMS only to the verified user; it requires separate `messages:send` permission and the user’s request. It cannot contact a match. Introductions and sharing contact details still require both people to agree through Property Bot. Do not promise automated outreach.

## Permissions for registered agents

| Scope | Tools |
| --- | --- |
| `profile:read` | `lookup_person` |
| `profile:write` | `remember_person` |
| `matches:read` | `find_matches` |
| `phone:verify` | `start_phone_verification`, `confirm_phone_verification` |
| `messages:send` | `send_text` (real SMS to the verified user only) |

`connection_status` and self-disconnection require a claimed registration, without a profile scope. Unknown permissions do not grant access. `delete_person` is not available to external agents. WorkOS controls the permissions issued during claiming; Property Bot enforces them on each call. This release does not offer a per-agent permission editor.

## Disconnect

For a regular OAuth connector, remove the Property Bot connection in your client’s connector settings. The `disconnect_agent` tool manages WorkOS registrations; it does not revoke an OAuth connector’s tokens.

For a registered agent, ask it to call `disconnect_agent` to disconnect itself. To manage another registration, connect with a regular OAuth MCP client, call `list_agent_connections`, and pass the chosen registration ID to `disconnect_agent`. `disconnect_agent` only affects a registration that has already connected to Property Bot at least once; a registration you claimed in WorkOS but never used must be revoked in WorkOS itself. Registered agents cannot list or disconnect other registrations. Your housing profile remains. Restarting the agent or refreshing its token does not undo disconnection; reconnect through a new registration and claim.

## Recover

- Wrong or expired phone code: request a fresh code; only the newest code works.
- No code: use the returned channel (an existing WhatsApp conversation can select WhatsApp), wait for rate limits, and retry. Do not guess codes or keep resending.
- Number linked to another login: use the original login or contact Property Bot through your existing conversation. Never transfer an account automatically.
- Changed number: recover/update the phone link through your own OAuth account. Registrations that have already connected to Property Bot are disconnected and need a new claim. A registration you claimed in WorkOS but never used is not in `agent_access` and must be revoked in WorkOS directly.
- `insufficient_scope`: explain the missing permission. Do not fall back to a shared service token.
- `agent_access_revoked`: explain that access stopped, with the profile preserved. Ask whether the user wants to reconnect.
- `agent_auth_unavailable`: wait and retry. The authentication provider is temporarily unavailable; don't ask the user to repeat their profile.

Human guide: https://property.bot/connect/
Privacy: https://property.bot/privacy
Help: https://property.bot/contact