Cartoply
Get started

Connect an AI agent to Cartoply

Cartoply runs an MCP server (Model Context Protocol — the open standard AI assistants use to work with external tools). An agent connected to it can do nearly everything an admin does in the dashboard: set up availability and event types, manage bookings, build an organization, draw and assign territories, invite the team, and read reports. You approve the access once, in your browser; after that the agent works on its own, and anything only a human may do (paying, granting calendar access) comes back to you as a link.

MCP endpoint: https://api.cartoply.com/api/mcp (Streamable HTTP)

Connect from the Claude app (desktop or web)

Cartoply works as a custom connector on paid Claude plans:

  1. Open Settings → Connectors in the Claude app (or claude.ai).
  2. Choose Add custom connector.
  3. Name it Cartoply and enter the server URL: https://api.cartoply.com/api/mcp
  4. Click Add, then Connect — the Cartoply consent screen opens; sign in if asked and approve.

After that, Cartoply's tools are available in your conversations (check the tools menu in the chat input to enable them). Try: "What's my Cartoply onboarding status?"

Connect from Claude Code

Add the server, then run /mcp inside a session and choose Authenticate — it opens the same consent screen in your browser:

claude mcp add --transport http cartoply https://api.cartoply.com/api/mcp

Any MCP client that supports OAuth works the same way: the server advertises its authorization setup via standard discovery (/.well-known/oauth-authorization-server on the API origin), clients register themselves automatically (dynamic client registration), and the flow uses the authorization-code grant with PKCE. You'll see exactly what you're granting on the consent screen before anything connects.

Let the agent start the signup (no account yet)

An agent can also bootstrap access for you, even before a Cartoply account exists. Connected without credentials, the server exposes exactly two tools:

  • start_signup — the agent gives your email address; Cartoply emails you a single-use claim link (valid 2 hours).
  • check_signup — the agent polls while it waits for you.

Opening the link is the one human step. If the address has no account, the page creates one — you set a password, accept the Terms of Service, and approve the agent's access in a single click. If you already have an account, the same link is just a sign-in-and-approve consent screen. Either way the agent receives its credentials seconds later and continues setting up. Nothing is created, shared, or accessible to the agent until you click.

Limits: claim links are single-use, expire after 2 hours, and at most 3 signup emails are sent to the same address per day. If a link expires, ask the agent to start again.

What an agent can do

The tool surface mirrors the admin dashboard:

  • Scheduling setup — weekly availability, date overrides, event types (durations, buffers, notice, daily caps, intake questions, screening rules, manual approval, instant-booking display), A/B experiments on org event types.
  • Bookings — list, cancel, reschedule, approve or decline requests, reassign to another rep, mark no-shows, pull reports.
  • Organization — create the org, invite members (individually or from a CSV), manage roles and member profiles, build groups, set the org schedule and notification preferences.
  • Territories — create polygon, radius, ZIP, city, county, or state zones; geocode addresses; import a Google My Maps KML/KMZ export; create a drive-time territory ("everything within N minutes' drive of this address", 5–120 minutes, traced along the real road network); assign zones to reps or groups.
  • Integrations — check calendar/Jobber connection state, choose which Google calendars count as busy, and fetch the connect links that need your browser.

What stays human-only

These are deliberately not available to agents, no matter what the agent asks:

  • Money out: issuing or denying refunds.
  • Destructive account changes: removing members, deleting an organization.
  • Billing: changing seats or the subscription, entering payment details. An agent can fetch a Stripe checkout or billing-portal link for you — completing it is yours.
  • OAuth consents: connecting Google/Outlook calendars, Stripe, PayPal, or Jobber happens on those providers' own consent screens, in your browser.

Access is scoped (mcp:read / mcp:write) and shown on the consent screen. Agent tokens expire after an hour and refresh automatically; the agent never learns your password.

A useful first prompt

Agents connected to Cartoply are told to start with the onboarding_status tool, which returns a live checklist — what's configured, what remains, and which remaining steps need a human link. So a good opening instruction is simply:

Set up my Cartoply account for my 4-person HVAC team: 60-minute service
calls 8am-6pm weekdays, each tech covers a 45-minute drive from their home
address (I'll give you the addresses), and send me links for anything that
needs me.

If something doesn't work

  • The claim email never arrived — check spam, then the daily cap (3 per address per day). The email comes from noreply@cartoply.com.
  • "This link has expired or was already used" — links are single-use and live 2 hours; the agent has to start a fresh signup, you can't retry the old link.
  • The agent reports a tool needs mcp:write — the connection was approved read-only; reconnect and approve the write scope.
  • "This team feature requires an active subscription" — org configuration tools respect the same paid gate as the dashboard; the agent can hand you the checkout link.
  • Drive-time territory errors mentioning the routing provider — the road-network service is temporarily unavailable; a plain radius territory works as a fallback, and the agent can replace it later.

For developers

The MCP server speaks Streamable HTTP (JSON responses, stateless), authenticates with OAuth 2.0 bearer tokens, and advertises discovery metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/mcp on the API origin. Public clients register at POST https://api.cartoply.com/api/oauth/register and must use PKCE (S256). The non-MCP REST surface used by the Zapier integration is documented on the API reference.