MCP server

Pulse Connect runs a hosted Model Context Protocol server. An AI assistant connects to it, the person connecting signs in to Pulse and chooses branches, and the assistant can then read that branch data and, with write access, add leads, quotes and notes, previewing each change first. No API key is created or pasted.

Environment	MCP server URL
Production (your company's live Pulse)	https://api.maidcentral.ai/api/connect/mcp
Staging (external pilot partners)	https://api.staging.maidcentral.ai/api/connect/mcp

The server speaks Streamable HTTP and signs in with OAuth 2.1 (dynamic client registration, PKCE). Supported clients are Claude (web, desktop and mobile), Claude Code, Codex, and other clients that receive the sign-in on a localhost redirect. Registration accepts only the Claude callbacks and http loopback redirects (127.0.0.1, localhost, [::1], any port), and browser requests are accepted only from claude.ai and claude.com; other web-hosted assistants can't connect.

Who can connect

• The person signing in needs the Manage Pulse Connect API Keys permission, which the Administrator role has.
• Each branch they choose needs Pulse Connect and its API keys turned on, and the MCP server turned on. MaidCentral turns these on per branch; until then the branch isn't offered on the consent screen.
• A person can hold 10 active connections per company. Connections don't count toward a branch's 10-key limit.

Sign-in and consent

1. Add the server URL to your assistant (below). It opens a Pulse page in your browser.
2. If the page asks for Your Pulse address, enter your company's address (the yourcompany in yourcompany.maidcentral.ai) and click Continue.
3. Sign in as you normally do, including two-factor authentication.
4. On the Connect … to Pulse page (it names your assistant), check what it will be able to do, tick the branches under Branches it can use, and click Allow. Deny sends the assistant back with nothing granted.

The sign-in request lasts 10 minutes. Read access covers customers, homes, services, jobs, schedules, billing, quotes, leads, reports and usage. Write access adds leads, quotes, notes and webhook tests.

Connect Claude

Claude on the web, desktop and mobile share connectors.

1. In Claude, open Settings > Connectors and click Add custom connector.
2. Name it, for example Pulse, and paste the server URL.
3. Click Connect and finish the Pulse sign-in.

On a Claude Team or Enterprise plan, an owner may need to add the connector for the organization first.

Connect Codex

codex mcp add pulse --url https://api.maidcentral.ai/api/connect/mcp
codex mcp login pulse

codex mcp login opens the Pulse sign-in and listens on a local port for the result. The Codex desktop app and IDE extension share the CLI's MCP configuration, so desktop users run codex mcp login pulse once in a terminal.

Connect Claude Code

claude mcp add --transport http pulse https://api.maidcentral.ai/api/connect/mcp

Then run /mcp in Claude Code, choose pulse and authenticate.

Tools

Tools are generated from the connect-v1 contract: each operation's id without connect, in snake_case (connectLookupCustomers is lookup_customers, connectListJobs is list_jobs). Two exceptions: connectSendWebhookTest is test_webhook, and verify_webhook_signature runs in Pulse with no matching operation. Arguments are the operation's path and query parameters and its JSON body fields; results are the API's JSON responses. The API reference documents each one.

Access granted	Tools
Read	44 read tools: every read operation, plus calculate_quote (prices without saving)
Read and write	57 tools: 48 reads (the 44 plus list_webhook_events, list_webhooks, get_webhook, list_webhook_deliveries), 7 confirm-gated writes, test_webhook and verify_webhook_signature

The cancel-service, move-job and skip-job reason lists aren't offered, because the MCP server can't cancel, move or skip.

Confirm-gated writes

create_lead, update_lead, create_quote, update_quote, create_customer_note, create_quote_note and create_technician_note.

1. A call without confirm changes nothing. It returns a preview of the exact request and branch, and a confirm_token.
2. After the user agrees, the assistant calls again with the same arguments plus confirm: true and that confirm_token.
3. A retry with the same token is idempotent: it answers "Already done" and writes nothing new.

Pulse requires the preview, not the user's agreement: an assistant that runs tools without asking can confirm its own changes. Grant write access only to assistants a person supervises.

A confirm_token works only for the change it previewed (same tool, branch and arguments) and expires after 1 hour. Changing anything, or repeating a change on purpose, needs a new preview.

Webhook tools

• test_webhook sends a test event to a subscription and returns the test's result, plus the first page of 5 deliveries from the last 30 days as GET /webhooks/{webhook_id}/deliveries returns it (ordered by delivery id, not newest first, so it may not include the test).
• verify_webhook_signature takes webhook_id, the raw body, and the Pulse-Connect-Signature and Pulse-Connect-Timestamp header values. It checks them against the subscription's stored signing secret and returns signature_valid, matched_secret (current, previous, or null when neither matches), timestamp_age_seconds and within_five_minutes. No tool accepts or returns a secret. Verifying the signature covers the same check in your own code.

Creating, changing, deleting or rotating webhooks isn't available through the MCP server.

Branches and branchId

Each ticked branch gets its own access, and the assistant can't reach any other branch.

• One branch granted: tools have no branchId.
• More than one: every tool takes a required branchId, listed with each granted branch's id and name. A write preview names the branch it will change.

Limits and usage

Every tool call runs through /api/connect/v1 as that branch, so scopes, branch isolation, rate limits and the monthly allowance apply exactly as they do to an API key. A write preview makes no request; test_webhook makes two. Usage emails go to the person who connected the assistant, as they do to a key's creator.

Disconnect

In Pulse, go to Settings > Integrations & System > Integrations > API Access > Pulse Connect API, find the assistant under AI assistant connections, and click Disconnect. That removes its access to every branch it was granted. Removing the connector in the assistant alone may leave the connection active in Pulse.

Expiry

What	Lasts
Connection	90 days from Allow; then connect again
Access token	1 hour; the assistant refreshes it on its own
Refresh token	30 days, renewed on each refresh

At its next token refresh (within an hour), Pulse ends a connection whose person is locked out or has lost the Manage Pulse Connect API Keys permission or access to every granted branch; a branch they lose access to drops out of the connection. The current access token works until then. To end a connection immediately, use Disconnect.

Troubleshooting

Problem	Fix
The assistant reports invalid_grant or keeps asking to sign in	The connection expired, was disconnected, or lost access. Remove the connector and connect again.
403 with mcp_disabled	The MCP server isn't turned on for any branch this connection was granted. Ask MaidCentral to turn it on for that branch.
Adding the server fails because its sign-in metadata answers 404	The MCP server isn't turned on for any branch yet. Contact MaidCentral.
Registration fails with invalid_redirect_uri, or calls get 403 forbidden_origin	The client isn't supported. Use Claude, Claude Code or Codex.
"No branch can connect"	None of your branches has Pulse Connect and the MCP server turned on. Contact MaidCentral.
"You can't connect an AI assistant"	You need the Manage Pulse Connect API Keys permission. Ask an administrator.
"Connection limit reached"	You have 10 active connections. Disconnect one you no longer use.
"Request expired"	The sign-in took longer than 10 minutes. Start again from the assistant.
A write tool says the confirm_token is for a different change or has expired	Call it without confirm to preview again, then confirm with the new token.