Cocal support: setup and everyday use

Get started

Cocal connects your calendars to the assistant you use. Set up your calendar accounts once, then connect Claude, ChatGPT, Gemini, or Claude Code.

Sign in to Cocal and connect a calendar account: Google Calendar, Outlook or iCloud Calendar. Outlook works with personal, work and school Microsoft accounts.
In Calendars, choose which calendars to enable. You can add more accounts and identify which calendars are yours, shared, or someone else’s.
Connect your assistant using the same Cocal account. Then ask: “Use Cocal to show my events tomorrow.”

Connecting a work or school account? Your organization may need to approve Cocal first. See if your organization blocks Cocal.

Connect an assistant

Choose your assistant below. Each uses the same hosted connection, so you don’t need to run a server. Sign in with the Cocal account that holds your calendars.

MCP server URL

https://mcp.cocal.io/mcp

Claude

Add Cocal as a custom connector.

Open Claude to start with Cocal’s name and server URL filled in.
Check the prefilled name and server URL, then click Add.
Click Connect, then sign in to Cocal and approve access.
Enable Cocal in the conversation’s connectors menu.

For Team or Enterprise, an authorized workspace administrator must add the connector before members can connect. Claude setup documentation.

ChatGPT

Add Cocal from Plugins as a custom server.

Open ChatGPT’s Plugins page. Choose the plus button, then Add custom MCP server.
Name it Cocal, add a short description, and enter https://mcp.cocal.io/mcp as the server URL under Connection.
Choose OAuth authentication, review the permissions, and choose Create as a plugin. Finish signing in to Cocal when prompted.
Review the tools and install the plugin. In a new chat, type @ and select Cocal.

Available actions depend on your plan and workspace permissions. If your account still shows Apps in Settings, use its custom-app setup and enable developer mode where required. ChatGPT setup documentation.

Gemini

Add Cocal as a custom Connected App on the Gemini website.

On the Gemini website, open Settings, then Connected Apps. If needed, open Personal Intelligence first.
Under Custom apps, choose to add a custom app.
Paste https://mcp.cocal.io/mcp, choose Next, then sign in to Cocal and approve the connection.
In Gemini, type @ and choose Cocal when you want it to work with your calendars.

Google currently requires a personal account, age 18 or over, US access, English, and Keep Activity turned on. Work and school accounts aren’t supported for custom apps. Gemini setup documentation.

Claude Code

Add Cocal from your terminal. Calendar actions work in text.

Run claude mcp add --transport http cocal https://mcp.cocal.io/mcp.
Restart Claude Code so it loads the new server.
On first use, finish the browser authorization flow with Cocal.

Run /mcp in Claude Code to check the connection or sign in again. Claude Code setup documentation.

Already connected? Manage access in Connected apps. For a first conversation, try one of the example prompts.

Manage your account

Use chat to plan your day. Use your Cocal account to choose what your assistant can access and manage the links and settings behind it.

Calendars: Add or reconnect accounts, enable calendars, and identify whose they are.
Connected apps: Connect another assistant or disconnect one you no longer use.
Booking: Create a booking link so people can choose from your available times. Choose which calendars block bookings, then set your hours, timezone, and buffers before sharing.
Invites: Ask in chat for an invite link to an event on Google Calendar, or one you organize on Outlook. Manage its guest limit or close it here. Guests join with their email address, no account needed.
Sync: Mirror events between two of your calendars, with updates every 15 minutes. Choose busy-only, limited, or full details. Two-way mirroring is available between Google calendars; Outlook and iCloud Calendar mirroring is one-way.
Preferences: Save plain-language calendar rules, such as leaving a lunch break. You can also edit them in chat. Changes apply to new conversations.
Settings: Choose when event changes need a preview before they go ahead.

What you can do

Read your schedule: List and search events, open event details, see calendar accounts, and check availability across enabled calendars.
Find and make plans: Get suggested times. Create, edit, and delete events, one at a time or several at once. Respond to invitations.

Where your assistant supports interactive content, Cocal shows calendar views and event cards. On other surfaces, including Claude Code, supported calendar actions work in plain chat. Available actions also depend on your assistant’s permissions.

Availability suggestions cover the calendars actually checked, not every guest’s schedule. A suggested time is not held. Calendar mirroring and detailed calendar settings are managed on the Cocal website.

Prompts to try

Copy a prompt into your connected assistant, or ask in your own words.

See your day
“Use Cocal to show my events tomorrow and flag any overlapping meetings.”
Find an opening
“Use Cocal to find a free half hour next week.”
Add focus time
“Use Cocal to block an hour for project planning next Tuesday at 10 AM.”
Find an event to change
“Use Cocal to find my project planning event next week.”

The focus-time prompt creates an event. For meetings with guests, review who will be notified.

Permissions and previews

Connecting a calendar account lets Cocal read your calendars and create, edit, and delete events, limited to the access you already have on each calendar. A read-only shared calendar stays read-only. See the exact Google and Microsoft permissions.

Reading or searching never changes your calendar. Creating, editing, deleting, and responding to invitations change your calendar. Changing links, accounts, or preferences changes your Cocal settings.

What gets a preview?

A preview shows the exact event and who will be emailed before Cocal creates or edits it. Check it, then confirm. Until you do, nothing is created, changed, or emailed. Choose when Cocal shows one under Event previews in Cocal settings:

Never. Cocal creates and edits events right away.
When inviting people outside your calendars. The default. Events with guests who aren’t on your own calendars get a preview. Events that involve only your own calendars are created right away.
When inviting people outside your calendars or the time conflicts. Adds events that overlap your calendars, repeat, or have times Cocal couldn’t fully check.
Always. Every event Cocal creates or edits gets a preview, even one with no guests.

How conflict checks and repeating events work

With the conflict-preview setting, a conflict is an overlap with another event on your own calendars. If Cocal can’t check all of them, because it couldn’t read one or you have more than it checks at once, it also shows a preview and says so. A repeating event always gets a preview, because Cocal checks only its first date. Overlaps with a partner’s or family member’s calendar and possible duplicates appear on a preview but don’t start one. When you edit an event, Cocal checks for conflicts only if the edit changes its time, and it previews any move of a whole series or change to a repeat rule.

For several events, Cocal checks the batch first and asks your assistant to prepare each required preview individually. Confirm each preview to apply its change. With Always, that means every event.

Deleting events, responding to invitations, and changing links or settings happen without a preview. When your assistant asks to use Cocal for these, read what it’s about to do before you allow it.

When people may be notified

Creating or editing an event with guests can send them an invitation or update from your calendar. Deleting an event emails guests a cancellation by default.
When you reply to an invitation on Google Calendar, Cocal doesn’t ask Google to email other guests unless you say so. On Outlook, your reply goes to the organizer, as it does in Outlook. For a repeating event, Cocal replies to just the date you pick unless you ask for the whole series.
When someone books through a booking link or joins through an invite link, the host’s calendar can send them an invitation. Bookings, reschedules, and cancellations can also send emails from Cocal.
Before Cocal changes an event, check the calendar, guests, timezone, and whether guests should be emailed. For a repeating event, say whether you mean one date or the whole series.

Disconnect or reconnect

Stop an assistant’s access: Open Connected apps in Cocal, find the assistant and choose Disconnect. You can also remove Cocal in that assistant’s connection settings. Your events and booking links stay in place.
Remove a calendar account: Open Calendars and choose Remove on that account. Cocal loses access to its calendars, and events already in them stay there. Features that use that account may stop working.
Restore access: Choose Reconnect on the affected account and finish signing in with that provider. For iCloud Calendar, enter a new app-specific password. If the assistant itself was disconnected, repeat its connection steps.

If your organization blocks Cocal

Work and school accounts are run by an administrator who decides which apps can reach your calendar. If yours requires approval, you’ll see a block when you connect. Cocal can’t get around it, but approval only happens once: after your admin approves Cocal, anyone in your organization can connect.

What to send your admin

I’d like to connect my work or school calendar to Cocal (cocal.io), a calendar assistant. Our organization’s settings need an admin to approve it once, and then anyone here can connect. Cocal only asks for calendar permissions on my behalf, so it can never see more than I can. Steps and the full permission list: https://cocal.io/support#organization-blocks

Outlook (Microsoft 365)

Most Microsoft 365 organizations require an admin to approve any app that reads calendars, so expect this with a work or school account. Personal Microsoft accounts, like Outlook.com and Hotmail, never need approval.

“Approval required.” Enter a reason and choose Request approval. Microsoft emails you when your admin decides. Then connect Outlook again.
“Need admin approval,” or an error code such as AADSTS90094 or AADSTS65001. There’s no request button. Choose the option to return to Cocal, where you’ll see an approval link. Copy it and send it to your admin with the note above.

Steps for your Microsoft 365 admin

Open the approval link from Cocal and sign in as a Cloud Application Administrator, Application Administrator or Privileged Role Administrator. Review the permissions and choose Accept. This approves Cocal for the whole organization.
Or, in the Microsoft Entra admin center, go to Entra ID → Enterprise apps → All applications, open Cocal, then Permissions → Grant admin consent. Cocal appears there after someone in your organization has tried to connect.
To let people ask for approval next time, turn on Enterprise apps → Consent and permissions → Admin consent settings → Users can request admin consent to apps they are unable to consent to. Requests then appear under Admin consent requests.

Cocal is a Microsoft verified publisher. It asks for delegated permissions only, so it acts as the signed-in person and can never reach more than they can:

Calendars.ReadWrite: read their calendars, and create, change, delete and reply to events when they ask.
MailboxSettings.Read: read their time zone.
User.Read, openid, profile, email: identify the account.
offline_access: keep the connection without signing in each time.

Cocal doesn’t ask for access to email. An admin can remove the approval anytime under Enterprise apps. Changes can take a few minutes to reach everyone.

Google Workspace

You may see “Access blocked: Your institution’s admin needs to review Cocal,” “This app is blocked,” or an error such as admin_policy_enforced or access_not_configured. If the screen offers to send your admin a request, use it. Otherwise send them the note above.

Steps for your Google Workspace admin

In the Google Admin console, go to Security → Access and data control → API controls → Manage App Access.
Under Configured apps, choose Configure new app, search for Cocal and choose who it applies to.
Set access to Trusted, or to Specific Google data with Google Calendar included. Changes can take some time to apply.

Cocal asks to read and write events, read the calendar list and read free/busy times. The exact permissions are in the privacy policy. Google’s own app access instructions cover every option.

iCloud Calendar

iCloud Calendar connects with an app-specific password, which needs two-factor authentication on your Apple Account. Apple Accounts managed by a company or school may not offer app-specific passwords. If yours doesn’t, connect a personal Apple Account.

If your admin says no

You can still connect a personal calendar. If your organization allows calendar sharing, you can also share your work calendar with a personal account you connect to Cocal. Cocal then sees it with the access the share gives you.

Troubleshooting

I can’t find the option to add Cocal

Check the requirements in your assistant’s setup steps. Availability can depend on your plan, account, region, or workspace administrator. Use the full server URL, including /mcp.

Cocal is connected, but my assistant is not using it

Enable Cocal for the conversation and name Cocal in your prompt. If another calendar connector is enabled, your assistant may choose it instead. Check your organization’s app or connector permissions, then try a new chat.

A calendar is missing or access expired

Check Calendars for the expected calendar account, enabled calendars, and connection warnings. Reconnect the affected account.

My organization blocked the connection

Work and school accounts can need an admin’s approval first. See if your organization blocks Cocal for what each message means, a note to send your admin, and your admin’s steps.

The calendar card does not appear

Check whether your assistant and the surface you’re using support interactive apps. Try its updated app or web version. You can still ask for event details and supported actions in plain chat.

An event change fails, times out, or only partly succeeds

Check the event, or list the affected dates, before you try again. A change can reach your calendar even when your assistant never hears back, so resending several events at once can create duplicates. Check each event’s result, your access to the calendar, and any reconnect warning.

A time or availability result looks wrong

Give the date and timezone, and check which calendars were included. If Cocal couldn’t read a calendar or didn’t check it, that doesn’t mean the time is free. For a repeating event, check whether you mean one date or the whole series.

A preview expired

Ask your assistant to prepare the change again, then review the new preview. An expired preview does not apply the proposed change. Check your calendar if you already tried to confirm it.

Data and support

Calendar results pass through Cocal to your connected assistant to answer your request. Cocal reads your events from your calendar provider when you ask, and the activity log records what was done, not event details. Cocal also stores your account and connection details, preferences, and what features like invite links, bookings, calendar mirroring, and previews need to work.

The privacy policy explains collection, sharing, retention, deletion, and Google API Limited Use. Your assistant provider’s policies also apply to information in the conversation. The Cocal terms apply to the hosted service.

When asking for help, include your assistant, calendar provider, what you tried, and any error message. Leave out passwords and private event details.

Get help Report a security issue