Using API v1? See what changes in v2, or the v1 docs

Build with Lovable

Lovable's agent can add Google Calendar and Microsoft Outlook to your app with Pyas. You connect the Pyas MCP server to Lovable once. The agent then gets the code for each task from Pyas, and you store a key as a secret. The key stays on the server, and the code works with the sandbox's sample people before anyone connects a real calendar.

Add Pyas to Lovable

  1. In Lovable, open Connectors, select Add custom at the top right, then select MCP server.
  2. For Server name, enter Pyas. For Server URL, enter https://mcp.pyas.io/sandbox. Leave the authentication on OAuth.
  3. Select Add & authorize. Sign in to Pyas, choose your app, and select Allow. See Sign in for what each permission allows.

The connection is yours. It gives Lovable's agent the Pyas tools while you build, and it is never part of your published app. Custom MCP servers are available on every Lovable plan. If MCP server can't be selected, an admin of your workspace has turned custom servers off.

The agent uses the Pyas tools that only read without asking. Before a tool that changes something, such as creating a test key, it shows a card for you to approve. To stop or remove the connection, open Connectors.

Ask for what you want

Ask in plain words, for example:

Add a button that lets people connect their Google or Outlook calendar, and show their events for the next week.

The agent checks your setup with setup_status and gets the code for each task with get_recipe. It adds your app's preview address to the allowed origins with update_app, and creates a test key with get_test_key. You confirm the address in Pyas, from the link it gives you. Every response from Pyas ends with the next step, so the agent knows what to do next.

Store the key

Store the test key as a secret named PYAS_API_KEY:

  1. In Lovable, open More, then Settings, then Secrets.
  2. Use the Add secret form. Don't paste the key into the chat.

Your app's server code reads the secret, and it never reaches the browser. A test key works only in your app's sandbox.

What Lovable adds

Lovable projects created since May 13, 2026 run on TanStack Start, and the code runs as server functions inside your app:

src/lib/pyas.server.ts                the Pyas client, on the server only
src/lib/pyas-connect.functions.ts     creates a connect session for the button
src/lib/pyas-events.functions.ts      the person's events for the next 7 days
src/lib/pyas-book.functions.ts        books the first free 30 minutes tomorrow
src/components/ConnectCalendar.tsx    the "Connect an account" button

Your pages call the functions directly, for example await listEvents(). The function that lists events looks like this:

src/lib/pyas-events.functions.ts

import { createServerFn } from '@tanstack/react-start'

const DAY = 24 * 60 * 60 * 1000

export const listEvents = createServerFn({ method: 'GET' }).handler(async ({ context }) => {
    // Loaded here, on the server: this file is also part of the browser's code.
    const { errorResult, pyas, signInRequired, subjectFor } = await import('./pyas.server')
    const subjectId = subjectFor(context)
    if (!subjectId) return signInRequired()
    try {
        const now = Date.now()
        const page = await pyas().events.list({
            subjectId,
            from: new Date(now).toISOString(),
            to: new Date(now + 7 * DAY).toISOString(),
            expand: true,
            sort: 'start',
            limit: 50,
        })
        // Titles are written by whoever sent the invitation: show them as text, never as HTML.
        return { events: page.data.map((event) => ({ id: event.id, title: event.title, startsAt: event.startsAt, endsAt: event.endsAt, isAllDay: event.isAllDay, provider: event.provider })) }
    } catch (error) {
        return errorResult(error)
    }
})

With a test key, the functions use the sandbox's sample person, so the events and booking work right away. The connect button shows a message from Pyas that connecting a real calendar requires a live key. This is expected.

In an older Lovable project, built with React and Vite, the agent adds Supabase Edge Functions in supabase/functions/ instead, and your pages call them with supabase.functions.invoke('pyas-events').

Receive webhooks

Ask the agent to receive Pyas webhooks. It adds a public route, src/routes/api/public/pyas-webhooks.ts, which verifies the signature of each delivery against the raw body before it reads the event.

The agent adds the endpoint to your sandbox with create_webhook, at your published address:

https://<your-app>.lovable.app/api/public/pyas-webhooks

Store the signing secret that create_webhook returns as a secret named PYAS_WEBHOOK_SECRET. See Webhooks for the events Pyas sends.

Go live

  1. Your app needs sign-in before people connect a calendar. Ask the agent to add sign-in, and to add it to the Pyas server functions. The functions then use the signed-in person. Until then, they respond with the code SIGN_IN_REQUIRED to every request made with a live key, so people's calendars never mix.
  2. In the Pyas dashboard, choose a plan and create a live key. Plans, payment and live keys are always done by you, in the dashboard.
  3. Replace the PYAS_API_KEY secret with the live key.
  4. Add your published address, such as https://your-app.lovable.app, to the app's allowed origins, and add a live webhook endpoint in the dashboard.