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)

If you do not have an AI provider account, use the Carti to ask read-only questions about an organization. Regular accounts include 100 metered AI credits; additional credits can be purchased when checkout is available. Your own MCP connection uses your provider account instead of Cartoply AI credits.

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

Connect from any other MCP client

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. There is no API key to paste and no client ID to request in advance — you'll see exactly what you're granting on the consent screen before anything connects.

Ask the agent to set itself up

If your assistant can edit files or run commands — Cursor, VS Code, Windsurf, Zed, or any coding agent — paste this and let it wire up its own configuration:

Add the Cartoply MCP server to this editor's MCP configuration.

  Name:      cartoply
  URL:       https://api.cartoply.com/api/mcp
  Transport: Streamable HTTP (a remote server, not a stdio command)
  Auth:      OAuth 2.1 with dynamic client registration and PKCE. There is no
             API key or client ID to enter - leave auth fields out entirely.

Use whichever config file this editor actually reads, match the shape of any
servers already in it, then reload so the server connects. A browser window
will open asking me to approve access - tell me when it does, because that
step is mine, not yours. Once you're connected, call the onboarding_status
tool and tell me what it returns.

Or add it by hand

Most clients use one of two config shapes. Cursor-style — .cursor/mcp.json in a project, or ~/.cursor/mcp.json to make it available everywhere:

{
  "mcpServers": {
    "cartoply": {
      "url": "https://api.cartoply.com/api/mcp"
    }
  }
}

VS Code-style — .vscode/mcp.json in a workspace, or the equivalent in your user profile — which also wants an explicit transport:

{
  "servers": {
    "cartoply": {
      "type": "http",
      "url": "https://api.cartoply.com/api/mcp"
    }
  }
}

Either way, leave the authentication fields out. Some clients offer a clientId or a headers block for servers that need a pre-registered app or a static token — Cartoply needs neither, and filling one in is the most common way to break the connection. Reload the client after saving; the consent screen opens the first time a tool runs.

ChatGPT

ChatGPT reaches custom MCP servers through developer mode. Turn it on under Settings → Apps → Advanced settings, then open Apps → Create, give it the endpoint above, choose OAuth as the authentication method, run Scan tools, and create it.

Two limits there are OpenAI's rather than ours: developer-mode connectors are web-only (they don't appear in the mobile app), and on the Pro plan they are restricted to read and fetch tools. So on Pro you can ask Cartoply questions — availability, bookings, who covers a ZIP code — but the agent cannot create or change anything, which rules out having it set the account up for you. Business, Enterprise and Edu plans allow write actions.

Clients that only speak stdio

Some minimal MCP clients can only launch a local process, and handle neither remote servers nor OAuth. Bridge one with mcp-remote, which runs on your machine, speaks stdio to the client, and performs the OAuth flow against Cartoply on its behalf:

{
  "mcpServers": {
    "cartoply": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.cartoply.com/api/mcp"]
    }
  }
}

It opens the same browser consent screen on first run and caches the tokens locally. Use a native remote connection wherever the client supports one — the bridge is an extra moving part that can fail on its own.

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

By default, agents cannot touch:

  • 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.

Refunds, refund denials, and member removal can be granted to a trusted assistant via an explicit high-risk permission (mcp:danger) that's spelled out on the consent screen when requested — it is never included by default, and the email-claim signup never grants it. Deleting an organization and changing the subscription are never available to agents, under any permission.

Access is scoped (mcp:read / mcp:write / mcp:danger) and shown on the consent screen. Every agent action is recorded in an audit trail with the acting agent, the tool used, and the outcome. 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.
  • The client connects but only shows two tools — that connection is unauthenticated, so it sees only start_signup and check_signup. Finish the consent flow in the browser and reload the client; the full surface appears once the token is in place.
  • The client demands a client ID, client secret or API key — Cartoply issues client credentials automatically, so there is nothing to paste. Leave the fields blank if the client allows it, and otherwise connect through mcp-remote as shown above.

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.