AI Hub (MCP Server): Setup & Usage

What the AI Hub is

The AI Hub is an HTTP endpoint that speaks JSON-RPC 2.0 and implements the 2025-06-18 Model Context Protocol specification. Compatible AI clients connect with a bearer token, discover the available tools through a standard handshake, and start running them.

Unlike a CSV export or a screenshot paste, the AI runs actual queries against the live database on your behalf. Ask "summarise my reviews from the last 30 days grouped by source", or "create a Local Search Grid scan for this dentist and re-run it every Monday at 9am", and the AI picks the right tool, builds the parameters, runs it, and reads the structured response back.

• MCP 2025-06-18 spec compliant with structuredContent result shape
• Single endpoint at /api/mcp on your white-label domain
• Bearer token authentication with scoped abilities
• Read-only by default, with a separate opt-in for write tools
• Per-organisation and per-location access enforced on every call
• PII redacted by default on private feedback and contact tools
• Google Business Profile metrics and search query terms exposed alongside reviews
• Agency-only Local Search Grid suite (gated on agency ownership) for the deep SEO surface
• Every tool call recorded in a per-agency audit log

Who can use the AI Hub

The AI Hub is available to any user with the api.access permission whose plan has the AI Hub feature enabled. Agency owners always have it; team members get it through their role.

Each connection you create is a Sanctum personal access token scoped to one named AI client. You can have as many connections as you need, and revoke any of them independently without affecting the others.

• Agency owners have access by default
• Team members need the api.access and api.mcp permissions in their role
• Agency customers get it when you switch AI Hub to Enabled on their custom plan. It is a separate plan toggle from API access
• Each connection is its own token with its own scope
• Revoking a connection invalidates it immediately

Supported AI clients

Any MCP-compatible client works. The configuration format is the same across all of them. The setup UI generates a ready-to-paste config snippet automatically using your custom domain.

• Claude Desktop (Anthropic)
• Claude Code (Anthropic)
• Cursor IDE
• VS Code with Copilot Chat
• ChatGPT custom connectors
• Any custom client that speaks MCP over HTTP

Creating your first connection

Open the dashboard, go to Resources -> Developer -> AI Hub (or Platform -> AI & Automation -> API & Webhooks, on the AI Hub tab), and click Create connection. Give it a descriptive name like "Claude Desktop" so you can tell your connections apart later.

Checkboxes control what the token can reach, all off by default: Allow write access (advanced) for drafting responses, tagging and preparing posts; Allow access to contact details (PII) so the AI can unlock names, emails and phone numbers; for agency owners only, Include Local Search Grid access (agency only) and Allow managing SMS providers (agency only); and Include Publishing, shown to users who may view posts, which adds the Google Business Profile post tools. Tick the ones you need before clicking Create connection: abilities are baked into the token and cannot be changed afterwards.

Agency owners also get Limit to these customers while Publishing is available. Search and pick customers, and the connection reaches only them; leave it empty to reach every customer. A connection limited to customers works only with AI assistants, not with the REST API. Its customers cannot be changed later. To change them, revoke the connection and create a new one. It cannot be combined with Allow managing SMS providers (agency only): SMS providers belong to the whole agency.

• Token is shown once at creation time, then never again
• Copy the generated mcpServers config snippet and paste it into your AI client
• Restart your AI client after saving the config
• Ask a natural-language question to trigger the first tool call

Config snippet for Claude Desktop

The AI Hub screen generates a ready-to-paste snippet using your domain and token. For reference, it looks like this:

• Paste the mcpServers block into your client config file
• For Claude Desktop: Settings -> Developer -> Edit Config
• For Cursor: Settings -> MCP and paste the same shape
• Save, restart, done

The full tool catalog

The server groups tools by purpose and risk level. The AI client automatically sees only the tools your token is allowed to call, which keeps its mental map accurate and prevents it from wasting calls on denied requests. Customer tokens never see the agency-only Local Search Grid tools, even if they have write access enabled.

Read tools, Read with PII tools, GBP read tools, agency-only Sales Intelligence tools, agency-only Local Search Grid tools (the deepest surface, including creating and scheduling scans), and Write tools that always hold for human approval. Together they cover every meaningful question a reputation operator might ask.

Connections created with Include Publishing also get the eighteen Publishing tools: seven that read posts, photos and settings, and eleven that prepare posts for a person to approve.

Agency owners' connections created with Allow managing SMS providers (agency only) also get the fourteen SMS provider tools: five that read the agency's providers, provider types, numbers and assigned organisations, and, with write access, nine that set up, change or delete providers, assign them to organisations, manage SignalHouse 10DLC registrations, send a test message and change the text added to every campaign SMS.

• Draft Google Posts with Claude or ChatGPT

Google Business Profile tools

Two tools expose Google Business Profile performance data for any location the caller can already see in the dashboard. These are customer-accessible: as long as the token has reviews:read (the existing review scope) and the user can open the location in the UI, they can pull the metrics.

list_gbp_metrics aggregates impressions, calls, direction requests, and website clicks for a date range and adds the previous-period totals to the same response, so the AI does not have to make a second call to compute trend deltas. list_gbp_search_terms returns the search query terms shoppers used to find the location, with monthly impression counts and a below_threshold flag for the terms Google masks for very-low-volume keywords.

Profile views and Photo views are no longer available from the Google Performance API and are not returned. Impressions, calls, direction requests, website clicks, and search query terms are still available.

• Scope: any user with reviews:read and access to the location
• Date range: up to 540 days per call
• Trend deltas: previous period totals included in the same response
• Search terms: monthly granularity, with masked terms surfaced explicitly

Local Search Grid tools (agency only)

The Local Search Grid surface gives AI clients the same control the dashboard gives you: list scans, drill into a single snapshot, browse the full snapshot timeline, pull the deep insights the report renders, create new scans on the fly, re-run them, and configure a recurring schedule.

Two things gate the Local Search Grid tools: the calling user must be the agency owner, AND the token must have been created with Include Local Search Grid access (agency only) ticked. Miss the checkbox and the tools stay hidden even for an owner. Create a new connection with it enabled. A customer with their own API token never sees these tools in the catalog, and any direct call attempt returns an access_denied JSON-RPC error.

The schedule_scan tool is the one most agencies reach for. Local rankings shift during business hours, so monthly rank tracking only tells the truth if it lands inside that window. Schedule a scan with frequency: monthly, scheduled_days: [1, 2, 3, 4, 5], scheduled_from: "09:00", scheduled_to: "17:00", and a timezone of your choice, and the platform fires a snapshot inside that window every month, automatically. Subscribe to the scan-completed webhook in Platform -> AI & Automation -> API & Webhooks to drop the result into your reporting stack.

• Visibility: agency-owner tokens created with the Include Local Search Grid access (agency only) checkbox ticked
• Read tools: list_scans, get_scan, get_scan_data_points (paginated per-pin), list_scan_snapshots, get_scan_insights
• Write tools: create_scan, run_scan, schedule_scan (all require mcp:writes)
• Webhooks: scan-completed and scan-failed for downstream automation
• Schedule cadence: cron worker ticks every 15 minutes

Permissions and scope enforcement

Every tool checks three things on every call. First, does the token hold the required Sanctum abilities (for example mcp:access, or mcp:writes for write tools). Second, does the token's owner have the required semantic permission (for example reviews.view or reviews.respond). Third, is the requested organisation or location inside the owner's access scope.

All three checks must pass. If any fails, the call is refused and recorded in the audit log as denied. Most tools return a JSON-RPC error with a specific code. The Publishing and SMS provider tools return the refusal as a tool result with isError set, carrying a code, a plain message and a fix that names the tool or setting to use instead, so the assistant can recover in the same conversation. The AI client can choose to surface this, retry with different parameters, or give up gracefully.

The Local Search Grid tools layer two more checks on top: the calling user must be the agency owner, AND the token must have been created with Include Local Search Grid access (agency only) ticked. Miss the checkbox and the tools stay hidden even for an owner, so create a new connection with it enabled. Customer tokens never see these tools in tools/list, and direct call attempts return access_denied.

• mcp:access is required for every tool
• mcp:writes is required for draft_review_response and tag_reviews; create_scan, run_scan and schedule_scan need mcp:writes AND local-search-grid:run (write access plus the Local Search Grid checkbox)
• reviews.pii is required to unlock PII with include_pii: true
• The Publishing read tools need publishing:read; the eleven Publishing prepare tools need mcp:writes, publishing:read and publishing:write (the Include Publishing and Allow write access (advanced) boxes)
• The SMS provider read tools need sms-providers:read; the ones that change anything, and send_test_sms, also need mcp:writes and sms-providers:manage (the Allow managing SMS providers (agency only) and Allow write access (advanced) boxes). Tenant ownership is required for all fourteen
• Tenant ownership is required for list_sales_intelligence_leads and get_sales_intelligence_lead
• Tenant ownership is required for every list_scans, get_scan, get_scan_data_points, list_scan_snapshots, get_scan_insights, create_scan, run_scan, and schedule_scan call
• Organisation and location scope always enforced, no override

Controlling PII exposure

The AI Hub treats PII (names, emails, phone numbers) as opt-in data. By default, list_private_feedback, list_contacts, and get_contact_activity return the same structure but with those fields stripped. This is the case even for agency owner tokens, so a read-only analyst token truly cannot send PII to an AI provider.

To unlock PII, two conditions must both hold on every call: the token was created with Allow access to contact details (PII) ticked, and the caller passes include_pii: true. Only agency owners, and team members whose role includes contacts.view, can tick that box: a token can never widen what its owner can already see.

• Redacted by default on every call
• Both reviews.pii permission and include_pii: true required to unlock
• Redactor runs server-side; PII never leaves the server unless both conditions pass
• Create separate tokens for PII work so revoking is targeted

Write tools and the approval queue

A small set of tools can modify data. All of them require mcp:writes on the token, and none of them bypass the existing moderation or scheduling pipelines.

When the AI calls draft_review_response, the resulting draft enters the Auto-Respond approval queue with status approval_requested and send_at set to null. It does not reach the review platform until a human opens the approval queue and clicks approve. If a matching Auto-Respond rule exists for the review's organisation or location, the rule's approval email fires so the reviewer gets notified the same way every other pending response is. If no matching rule exists, a minimal "MCP Drafts" rule is created automatically (with use_ai off and require_approval on) to carry the draft.

tag_reviews attaches or detaches tags on up to 50 reviews per call. Tagging is a soft, reversible operation, but it still requires write access. The flag sentinel tag is reserved and cannot be used through the tool.

The Publishing tools prepare posts and can set or move a post's time, but never approve or publish. A post an assistant drafts or edits waits for a person to approve that exact version, in Posts or from the approval email link. Prepare tools need Allow write access (advanced) and Include Publishing on the connection, and the user's own Publishing permissions at the location.

The agency-only SMS provider tools change the agency's SMS setup directly, as the SMS page does: they set up, change or delete providers, assign them to organisations, manage SignalHouse registrations and change the text added to every campaign SMS. No SMS provider tool sends a campaign message; send_test_sms sends one real test text to the number the person gives, at most five a minute and never to a blocked number. API keys given to these tools also pass through your AI provider; they are saved encrypted, never shown back, and replaced with [redacted] in the audit log.

The agency-only create_scan, run_scan, and schedule_scan tools require both mcp:writes on the token and agency ownership for the calling user. create_scan and run_scan queue background work (no instant-publish risk; the cron worker and webhooks handle delivery). schedule_scan only writes the recurrence configuration; the first scheduled snapshot still lands inside the configured day-of-week and time-of-day window.

Reading the audit log

Every tool call writes a row to the mcp_tool_calls table inside your agency account. The row captures the caller, token, tool name, redacted parameters, duration, response size, row count returned, and result status. Tokens, emails, and phone numbers in the parameters are stripped before storage so the log itself does not become a PII surface.

Open the AI Hub dashboard to browse the log. You can filter by date range, tool name, and result status (ok, denied, error). The dashboard also shows a per-tool breakdown, a call-volume chart, and the recent activity for every connected client.

Rows older than 90 days are pruned automatically by a daily background job, so the audit table stays bounded even on busy accounts.

• One row per tool call, captured asynchronously through a queue so it never blocks the call
• Redacted parameters only, never raw tokens or PII
• Correlation IDs let you group all tool calls from a single AI prompt
• 90-day retention, pruned automatically

Rate limits

Two stacked rate limits protect the server. 120 calls per minute per token, and 600 calls per minute across the entire workspace. Both limits apply simultaneously. Hitting either returns HTTP 429 with a Retry-After header and a JSON-RPC error body so the AI client can back off and retry cleanly.

In practice, a single Claude conversation usually fires 5 to 15 tool calls per question, so even a team of several analysts working against the same workspace will not touch these limits.

Correlation IDs for tracing

AI clients that support it can pass an X-Correlation-Id header. The server echoes it back on the response and stores it in the audit log. That makes it trivial to group all of the tool calls a single AI prompt generated, which is the fastest way to debug "why did Claude give that answer".

The header accepts any string up to 64 characters. If no header is sent, the server proceeds without one and the audit row's correlation_id is null.

White-label behaviour

The MCP endpoint always resolves on your own white-label domain, for example https://app.your-agency.com/api/mcp. The serverInfo.name returned during the MCP initialize handshake uses your agency company name. The AI Hub screen, the audit log dashboard, the API documentation, and the generated config snippet all use your agency branding.

Nothing in the MCP protocol exchange mentions EmbedMyReviews. The setup is identical for agency customers on white-label domains.

Troubleshooting

Common questions