MCP server

Cooledge runs a remote MCP (Model Context Protocol) server so AI assistants can work with your business data directly. Claude, Cursor, ChatGPT and any other MCP-capable client can search customers, check the calendar, create jobs, draft quotes, draft replies to customers and more, always within the permissions you grant.

The server lives at:

https://app.cooledge.com.au/api/mcp/mcp

It speaks the Streamable HTTP transport. Every tool call runs through the same permission scopes, plan checks and rate limits as the REST API.

Connect with OAuth (recommended)

Most MCP clients connect with one click. Add the server URL and the client walks you through it:

Add a custom connector or MCP server in your client and paste the server URL above.
Your browser opens a Cooledge consent screen. Sign in as the account owner if you are not already, because only the owner can approve a connection.
Review what the app is asking for and choose Allow access.
The client finishes the connection automatically. You are done.

Client specifics:

Claude (claude.ai and Claude Desktop): Settings, then Connectors, then "Add custom connector". Paste the server URL.
Cursor: add the server under MCP settings with the URL above and follow the sign-in prompt.
ChatGPT: add Cooledge as a connector in settings where MCP connectors are supported on your plan.

Behind the scenes the client registers itself, sends you to https://app.cooledge.com.au/oauth/authorize for consent and exchanges a one-time code for tokens. Access tokens rotate automatically, so a connection keeps working for as long as you leave it connected and use it at least every 30 days.

Connect with an API key

Clients that do not support OAuth can authenticate with an API key from Settings, then Developers, created by the account owner. Configure the client to send it on every request, either as a bearer token or in the X-Api-Key header:

Authorization: Bearer ck_live_AB12CD_your_secret_here

Key-based connections have the same abilities as OAuth connections, with one difference: a key acts as the business, not as a person, so the task tools cannot use "me". The difference is lifecycle: keys live until you revoke them, while OAuth connections can be disconnected per app.

What the assistant can do

The server exposes 36 tools over your Cooledge data. Reads cover business context, the calendar, customers, jobs, quotes, invoices, bookings, leads, tasks, your staff list, overdue invoices and the team inbox. Writes cover creating and updating customers, sites, jobs, bookings, leads and tasks, completing and reopening tasks, creating ducted quotes, adding invoice lines, sending quotes and invoices and writing reply drafts.

Every tool respects the scopes on the credential. An OAuth consent screen lists the scopes an app asked for. If you approve a narrower list, tools outside it return a permission error the assistant can read and explain.

Tasks

Five tools let an assistant read and manage your team's tasks. A task is a to-do with an optional due date and reminder. To block time on the calendar, the assistant uses create_booking with booking_type "event" instead.

Tool	Scope	What it does
`list_staff`	`tasks:read`	Lists your active staff with their id, name and role, so a person named in a request can be matched to an assignee. Filters on any part of a name. When more than one person matches, the assistant asks you which one.
`list_tasks`	`tasks:read`	Lists tasks, overdue first. Views are `mine`, `team` or `unassigned`. Filters by status (`open`, `done` or `all`), due bucket (`overdue`, `today`, `upcoming` or `none`), assignee, linked record or a title search. A cursor reads more.
`create_task`	`tasks:write`	Creates a task with an assignee, a due date or date and time, one reminder, a link to one job, quote, lead or customer and an optional repeat. The assignee is emailed unless they created it.
`update_task`	`tasks:write`	Changes a task's title, description, assignee, due, reminder or link. On a repeating task, scope `future` also changes the tasks still to come. Reassigning emails the new assignee.
`complete_task`	`tasks:write`	Marks a task done (`done: true`, the default) or reopens it (`done: false`). Completing a repeating task creates the next one. The creator is notified when someone else completes it.

Assignees are "me", a staff id from list_staff or null for unassigned. "me" is the person who approved the connection, and the mine view lists their tasks, which is the default view for an OAuth connection. An API key acts as the business rather than a person, so it cannot use "me" or the mine view (either one gets a 400 error) and its default view is team. Task tools also need the person who approved an OAuth connection to still be an active owner or admin. If they are not, the tools return a permission error until an owner reconnects the app. Tasks are not available on the Designer plan.

New OAuth connections include tasks:read and tasks:write in the default set, and the consent screen shows them as View tasks and Create, update and complete tasks. A connection made before Tasks does not have them. Disconnect it and connect again to approve them. An API key cannot gain scopes, so create a new key with the Tasks row ticked. The Full access preset ticks Read and Write on that row, and Read-only ticks Read.

Messages

Six tools let an assistant read your conversations and draft replies. A person on your team reviews and sends every draft. No tool sends or schedules a message: a draft waits in its conversation in Cooledge, marked with who drafted it, until someone sends it, schedules it or deletes it.

Tool	Scope	What it does
`list_conversations`	`messages:read`	Lists conversations newest activity first, filtered by state, channel, a search on the customer's name, phone or email, unreplied and unknown senders.
`get_conversation`	`messages:read`	One conversation with its latest 30 messages and calls and the drafts waiting in it. Internal comments only when asked. A cursor reads older messages.
`list_drafts`	`messages:read`	Drafts waiting for a person, newest first, across the business or for one conversation.
`create_draft`	`messages:draft`	Writes an SMS or email draft to the conversation's own customer, one of their contacts or the unknown sender. It cannot choose another address, CC, BCC or files.
`update_draft`	`messages:draft`	Changes the words of a draft this connection wrote, while it is still waiting.
`delete_draft`	`messages:draft`	Deletes a draft this connection wrote, while it is still waiting.

The Messages scopes are not in the default set an app gets when it connects without asking for particular scopes. Existing connections and keys do not gain them either. An app has to request messages:read and messages:draft, or you can use an API key with the Messages row ticked. At most 3 drafts from apps can wait in one conversation and 200 in a business. The Messaging API guide has the rules the tools share with the REST endpoints.

Disconnect an app

Go to Settings, then Developers, then Connected apps. Every active OAuth connection shows the app name, who approved it, its scopes and when it was last used. Owners and admins can see the list, and only the account owner can disconnect an app. Disconnect cuts off access immediately. The app can reconnect later only by going through consent again.

Errors and limits

MCP tool calls share the platform limits: 120 requests per minute per credential by default. Rate limit, permission and validation problems come back inside the tool result so the assistant can adjust and retry sensibly. If your plan does not include API access, tool calls explain that too.