Clients

Create, read, update, and manage the client businesses your agency manages.

• Readlist_clientsList the client businesses this agency manages, newest first. This is the starting point for anything about clients: use it to find a client and its id before calling get_client_by_id, or to answer questions like "how many active clients do we have?", "which clients are assigned to a rep?", or "show clients with a health score under 40". All filters are optional and are combined together (a client must match all of them); status, representativeIds, and goals each accept multiple values and match any of them. Returns a page of client summaries plus a running `total` and a `nextCursor` — each summary has the client's name, industry, status, goal, health score, number of locations, Google rating and review count, plan, created date, and assigned representative. To page through more, call again passing the returned `nextCursor`. You don't pass an agency — it comes from your credentials. Sensitive data (login credentials, portal secrets) is never returned.
• Readget_client_by_idGet the full details of a single client by its id. Use this once you know which client you want — typically after list_clients gives you the id — when the list summary isn't enough. Returns everything about that one client: full business profile and contact info, the assigned representative and who created the client, health score and rating/review metrics, whether the customer-portal invite is pending or accepted, listings data, and which plan the client is on. You don't pass an agency — it comes from your credentials, and a client from another agency is never returned. Sensitive data (login credentials, portal secrets) is never included. To look up or find a client id first, use list_clients.
• Writecreate_clientAdd a new client (a business your agency will manage) and run its onboarding automatically — it assigns a plan, sets up the client's customer-portal login, and computes an initial health score. You must provide three things: the business name, the client's primary contact email (this becomes their portal login and can't be changed later), and the id of the team member who will own the client. Optionally include Google Business details (get them from search_google_business) to fill in the profile, and a tracking keyword to start monitoring the client's local search rank. IMPORTANT: when you pass a placeId, this also creates the client's FIRST LOCATION from that Google place — which is what starts the listings, reviews and AEO work — and returns its id as `locationId`. Do not follow this with create_location_from_google or create_location for the same business: that would create a duplicate location. If you passed a placeId and `locationId` still comes back null, `locationSkipped` says why (for example `location_limit` means the agency is at its plan's location cap, and the client will have no listings or reviews until a location is added) — tell the user rather than retrying. Fails if a client with the same business name already exists (including an archived one — the error names its id so you can call reactivate_client instead of creating a new one). New clients are visible to your whole team. You don't pass an agency — it comes from your credentials.
• Writeupdate_clientEdit an existing client's editable fields. Pass only the fields you want to change. The client's primaryContactEmail (their portal login) can never be changed here. Identify the client by its id (from list_clients, create_client, or — for an archived client, which list_clients and get_client_by_id never return — the id create_client's duplicate_archived error names). Works on an archived client too, without reactivating it first. Returns the updated client, or throws if not found. You don't pass an agency — it comes from your credentials.
• Writedelete_clientRequest deletion of a client. This never permanently destroys anything. If the client has any locations this SCHEDULES it: the client and every one of its locations are archived at the end of the current billing period, and until then everything stays fully active and still billed — the archival can be called off with cancel_scheduled_client_deletion while it's still pending, or undone with reactivate_client once it has actually archived. A client with no locations at all (or none still live) is archived immediately instead of being scheduled (also undoable with reactivate_client). The response's `outcome` field says which happened ("scheduled" or "archived") — report that back rather than assuming. Identify the client by its id (from list_clients).
• Writecancel_scheduled_client_deletionCall off a pending client deletion, so a client scheduled to archive at the end of the billing period carries on as normal. This also releases the locations that were scheduled along with it. Only works while the deletion is still pending — once the period has ended and the client is actually archived, call reactivate_client instead.
• Writereactivate_clientRestore an archived client, bringing back the client and every location that archived along with it in the same request (a location archived separately, before or independently of that request, is not touched). Undoes what delete_client's schedule did once it actually reached the end of the billing period (a still-PENDING one should use cancel_scheduled_client_deletion instead — this tool is for a client that is already archived). A client that isn't currently archived is left unchanged rather than erroring. list_clients and get_client_by_id never return archived clients, so the only way to learn an archived client's id through this MCP surface is create_client's error when the business name matches one — it names the id to pass here.
• Writeinvite_clientSend (or resend) the client-portal invite email to a client's primary contact — a passwordless magic link they use to log into their customer portal. Resending does NOT invalidate a previously sent link: every link minted stays independently valid until it's used once or reaches its own 7-day expiry, so a resend leaves both the old and new email usable. Fails if the client has no primaryContactEmail set. Identify the client by its id (from list_clients). Returns the invite link that was sent.
• Readsearch_google_businessSearch Google for a business by name and return the top matches, each enriched with full details (name, address, addressComponents, phone, website, GBP URL, category, businessStatus, rating, reviewCount, placeId, latitude, longitude). Use to find a business to onboard, then pass the chosen match's fields to create_client. Returns an empty list if nothing matches or Google is unavailable.
• Readlist_google_accountsList the Google Business Profile accounts already connected for a client, so you can pick one to import locations from. Returns each account's connectionId, the signed-in email, whether its credentials are still valid, its fetch status, how many locations are already connected, and how many have been fetched and are available to import. Start here for a Google import; if an account has 0 available, call trigger_google_fetch, then get_google_listings. You don't pass an agency — it comes from your credentials.
• Writetrigger_google_fetchStart fetching the locations under a connected Google account so they become browsable/importable. This runs in the background; poll list_google_accounts and watch the account's fetchStatus and available count, then call get_google_listings. Starts (or restarts) the background fetch and returns once it's queued. You don't pass an agency — it comes from your credentials.
• Readget_google_listingsBrowse the Google locations that have been fetched for a connected account (call trigger_google_fetch first if none are available). With no folder, returns the list of Google Business account folders (each with a location count). With a folder, returns that folder's locations — each with its fetchedListingId, resource name, name, address, verification state, whether it's already imported (connected), and whether its category maps to a supported one. Pass the fetchedListingIds you want to create_location_from_google. Optionally filter a folder by search text. You don't pass an agency — it comes from your credentials.
• Writecreate_location_from_googleImport one or more fetched Google locations into new business locations under a client, pulling their full Google profile (name, address, hours, categories, photos, etc.). Get the fetchedListingIds from get_google_listings. Imports up to 10 per call. Each new location is submitted to the other directories automatically (it's already live on Google). Returns the created location ids (and any that failed, with the reason). You don't pass an agency — it comes from your credentials.