Build a Gmail Email Sync Automation

What we’ll do

Install the Pica MCP Server.
Connect your .
Set up a starter project.
Add some rules for the LLMs to understand BuildKit.
Prompt the LLM to build your tool.

Architecture Overview

This tutorial demonstrates a production-ready Gmail email sync system that:

Authenticates users via AuthKit’s secure multi-tenant OAuth flow
Syncs emails hourly using cron jobs or scheduled functions
Stores data in Supabase for scalable, real-time access
Processes emails through BuildKit MCP server for AI-powered analysis

Install the Pica MCP Server

First, let’s add the Pica MCP Server to your development environment. Select your preferred tool and follow the instructions.

In the Cursor menu, select “MCP Settings” and update the MCP JSON file to include the following:

MCP Settings

{
  "mcpServers": {
    "pica": {
      "command": "npx",
      "args": ["@picahq/mcp"],
      "env": {
        "PICA_SECRET": "your-pica-secret-key"
      }
    }
  }
}

Replace your-pica-secret-key with your actual Pica Secret Key from the link below.

Grab your API Key

Navigate to your Pica dashboard to access your API keys.

Connect your accounts

Now we need to connect your so we can test our tool after we build it.

Required Environment Variables

You’ll need these keys in your environment:

Environment Setup

# Pica Configuration
PICA_SECRET_KEY=your_pica_secret_key

# Supabase Configuration  
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Application Configuration
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000

AuthKit Integration Setup

1. Install Dependencies

Package Installation

npm install @picahq/authkit-node @picahq/authkit
npm install @supabase/supabase-js
npm install node-cron
npm install @modelcontextprotocol/sdk

2. Supabase Database Schema

Database Schema

-- Create emails table
CREATE TABLE emails (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id TEXT NOT NULL,
  connection_key TEXT NOT NULL,
  message_id TEXT UNIQUE NOT NULL,
  thread_id TEXT,
  subject TEXT,
  sender TEXT,
  recipient TEXT,
  body TEXT,
  snippet TEXT,
  labels TEXT[],
  is_unread BOOLEAN DEFAULT false,
  received_date TIMESTAMPTZ,
  processed_at TIMESTAMPTZ DEFAULT NOW(),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create sync_status table for tracking
CREATE TABLE sync_status (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id TEXT NOT NULL,
  connection_key TEXT NOT NULL,
  last_sync_at TIMESTAMPTZ,
  next_sync_at TIMESTAMPTZ,
  emails_synced INTEGER DEFAULT 0,
  status TEXT DEFAULT 'active',
  error_message TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes for performance
CREATE INDEX idx_emails_user_id ON emails(user_id);
CREATE INDEX idx_emails_message_id ON emails(message_id);
CREATE INDEX idx_emails_received_date ON emails(received_date DESC);
CREATE INDEX idx_sync_status_user_id ON sync_status(user_id);
CREATE INDEX idx_sync_status_next_sync ON sync_status(next_sync_at);

-- Enable Row Level Security
ALTER TABLE emails ENABLE ROW LEVEL SECURITY;
ALTER TABLE sync_status ENABLE ROW LEVEL SECURITY;

-- Create RLS policies
CREATE POLICY "Users can only access their own emails" ON emails
  FOR ALL USING (auth.jwt() ->> 'sub' = user_id);

CREATE POLICY "Users can only access their own sync status" ON sync_status
  FOR ALL USING (auth.jwt() ->> 'sub' = user_id);

3. AuthKit Button Component

Component: components/AuthKitButton.tsx

'use client';

import { useAuthKit } from "@picahq/authkit";
import { useState } from "react";

interface AuthKitButtonProps {
  userId: string;
  onConnectionSuccess?: (connection: any) => void;
}

export function AuthKitButton({ userId, onConnectionSuccess }: AuthKitButtonProps) {
  const [isConnecting, setIsConnecting] = useState(false);

  const { open } = useAuthKit({
    token: {
      url: "/api/authkit",
      headers: {},
      body: { userId },
    },
    onSuccess: (connection) => {
      console.log("Successfully created connection:", connection);
      setIsConnecting(false);
      onConnectionSuccess?.(connection);
    },
    onError: (error) => {
      console.error("Error creating connection:", error);
      setIsConnecting(false);
    },
    onClose: () => {
      console.log("AuthKit modal closed");
      setIsConnecting(false);
    },
  });

  const handleConnect = () => {
    setIsConnecting(true);
    open();
  };

  return (
    <button
      onClick={handleConnect}
      disabled={isConnecting}
      className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
    >
      {isConnecting ? "Connecting..." : "Connect Gmail"}
    </button>
  );
}

System Implementation

The system consists of several key components working together for automated Gmail email synchronization.

Set up a starter project

Choose your preferred framework and follow the setup steps to get your starter project up and running.

Clone and install dependencies.

Clone Repository

git clone https://github.com/picahq/buildkit-vercel-ai-starter.git && cd buildkit-vercel-ai-starter

Install Dependencies

npm install

Set up environment variables.

.env.local (root directory)

OPENAI_API_KEY=your_openai_api_key_here

Run the development server.

Start Server

npm run dev

Open your browser.
Navigate to http://localhost:3000 to see the chat interface.

Add some rules for the LLMs to understand BuildKit

BuildKit Rules for Cursor

Copy the rules content and paste them into .cursor/rules/buildkit.mdc in the root of your project.

BuildKit Rules for Cursor

---
description:
globs:
alwaysApply: true
---

# Pica Buildkit – LLM Rules

**Role**
You are an expert integration developer working with **Pica MCP**. You can:
- Build tools for **Vercel AI SDK** and **LangChain**
- Scaffold and implement **full MCP servers** (model context protocol)
- Use the **Pica MCP** utilities to discover actions, fetch schemas/knowledge, and execute API calls.

Pica is not in your training set; always follow the discovery steps below to build correctly.

---

## 0) Hard Requirements & Guardrails

1. **Do not overwrite existing projects**
   - Before generating/scaffolding, check the current directory.
   - If a project is detected (e.g., \`package.json\`, \`pnpm-lock.yaml\`/\`yarn.lock\`/\`package-lock.json\`, \`.git\`, \`mcp.json\`, \`src/\` with buildkit markers), **do not** create a new project. Instead, add or modify files minimally and explicitly.

2. **Always discover before coding**
   - Use Pica MCP tools to discover integrations and actions, and to fetch **action knowledge** (input schema, path, verbs, content-types, pagination, auth notes, rate limits) **before writing any tool code**.

3. **Prefer Pica MCP if available**
   - If the Pica MCP is available in the environment, use its tools to list integrations, fetch platform actions, and get action knowledge; only then implement.

4. **Use the provided executor**
   - When executing a Pica action from a tool or MCP, use \`picaToolExecutor\` (below).
   - Build its \`path\`, \`method\`, \`query\`/\`body\`, and \`contentType\` from **get_pica_action_knowledge**.

5. **Secrets**
   - Never print secrets. Expect \`PICA_API_KEY\` and user-provided \`{PLATFORM}_CONNECTION_KEY\` at runtime. Validate and fail fast if missing.

6. **Output discipline**
   - Generate **ready-to-run code** with minimal placeholders.
   - Provide install/run/test snippets when you scaffold.

7. **Connection key environment**
   - Remember to add the connection key to the environment and not as an argument to the tool. As PLATFORM_CONNECTION_KEY (i.e. GMAIL_CONNECTION_KEY)

8. **Type generation from action knowledge**
   - Remember to add types for what you need to based on the action knowledge.

---

## 1) Pica MCP Utilities (Call These First)

When asked to build a tool or MCP, follow this order:

1) **list_pica_integrations**
   _Goal_: Surface connectable platforms and their slugs/ids.
   _User help_: Tell the user how to add/authorize integrations at \`https://app.picaos.com/connections\`.

2) **get_pica_platform_actions(platformId | slug)**
   _Goal_: Find the action the user cares about (e.g., Gmail \`listMessages\`, Notion \`queryDatabase\`, Slack \`chat.postMessage\`).

3) **get_pica_action_knowledge(actionId)**
   _Goal_: Fetch the **canonical contract** for that action — HTTP method, path template, parameters (query, path, body), headers, content-type, limits, pagination rules, success/error shapes, and sample requests.

> Only after step (3) do you write code.

---

## 2) Pica Tool Executor (Boilerplate Example)

> **Note**: This is **boilerplate** — do **not** treat as final or language-specific. It simply shows how to call the Pica passthrough API. You may adapt it to any language or SDK as long as the call structure is preserved.

\`\`\`ts
export async function picaToolExecutor(
  path: string,
  actionId: string,
  connectionKey: string,
  options: {
    method?: string;
    queryParams?: URLSearchParams;
    body?: any;
    contentType?: string;
  } = {}
) {
  const { method = 'GET', queryParams, body, contentType } = options;

  const baseUrl = 'https://api.picaos.com/v1/passthrough';
  const url = queryParams
    ? \`\${baseUrl}\${path}?\${queryParams.toString()}\`
    : \`\${baseUrl}\${path}\`;

  // Default to JSON unless overridden by action knowledge
  const headers: Record<string, string> = {
    'content-type': contentType || 'application/json',
    'x-pica-secret': process.env.PICA_API_KEY || '',
    'x-pica-connection-key': connectionKey,
    'x-pica-action-id': actionId,
  };

  const fetchOptions: RequestInit = { method, headers };

  if (body && method !== 'GET') {
    fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
  }

  const response = await fetch(url, fetchOptions);
  if (!response.ok) {
    const text = await response.text().catch(() => '');
    throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`);
  }
  return response.json().catch(() => ({}));
}
\`\`\`

**Key Points**
- Default \`content-type\` = \`application/json\` unless overridden by \`get_pica_action_knowledge\`.
- No Gmail-specific logic.
- Example only — adapt freely to your language/runtime.

---

## 3) Building Tools (Vercel AI SDK & LangChain)

1. Ask the user which **integration** & **action** they want (or infer from their ask).
2. Call the Pica MCP utilities (Section 1).
3. From \`get_pica_action_knowledge\`, derive:
   - \`actionId\`
   - \`method\`, \`path\`, \`query\` keys, \`body\` shape, \`contentType\`
   - Pagination fields and rate limits
4. Write the tool with a strict \`inputSchema\` and a clear \`execute\` that:
   - Validates user input
   - Builds query/body safely
   - Calls \`picaToolExecutor\`
   - Normalizes output (add a short \`summary\`)

### Complete Gmail Tool Example

Here's a real-world example of a Gmail tool that fetches email contents with proper filtering:

\`\`\`ts
import { z } from 'zod';
import { tool } from 'ai';
import { picaToolExecutor } from '../picaToolExecutor';

export const loadGmailEmails = tool({
  description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.',
  inputSchema: z.object({
    label: z.string().optional().describe('Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)'),
    numberOfEmails: z.number().min(1).max(50).default(10).describe('Number of emails to retrieve (1-50, default: 10)'),
    query: z.string().optional().describe('Additional Gmail search query (e.g., "from:john@example.com", "subject:project")'),
  }),
  execute: async ({ label, numberOfEmails = 10, query }) => {
    try {
      // Build the search query
      let searchQuery = '';
      if (label) {
        searchQuery += \`label:\${label}\`;
      }
      if (query) {
        searchQuery += searchQuery ? \` \${query}\` : query;
      }

      // Prepare query parameters for list messages
      const queryParams = new URLSearchParams({
        maxResults: numberOfEmails.toString(),
        ...(searchQuery && { q: searchQuery })
      });

      const connectionKey = process.env.GMAIL_CONNECTION_KEY;

      // First, get the list of message IDs using picaToolExecutor
      const listMessagesResult = await picaToolExecutor(
        '/users/me/messages',
        'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ',
        connectionKey,
        { queryParams }
      );

      if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) {
        return {
          emails: [],
          totalFound: 0,
          message: 'No emails found matching the criteria',
          summary: 'No emails found matching the criteria'
        };
      }

      // Extract email details from each message
      const emails = [];

      for (const messageRef of listMessagesResult.messages) {
        try {
          // Prepare query parameters for get message
          const messageQueryParams = new URLSearchParams();
          messageQueryParams.set('format', 'full');
          messageQueryParams.append('metadataHeaders', 'From');
          messageQueryParams.append('metadataHeaders', 'To');
          messageQueryParams.append('metadataHeaders', 'Subject');
          messageQueryParams.append('metadataHeaders', 'Date');

          // Get full message details using picaToolExecutor
          const messageResult = await picaToolExecutor(
            \`/users/me/messages/\${messageRef.id}\`,
            'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw',
            connectionKey,
            { queryParams: messageQueryParams }
          );

          if (messageResult?.payload?.headers) {
            const headers = messageResult.payload.headers;

            // Extract header information
            const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || '';
            const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || '';
            const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || '';
            const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || '';

            // Extract body content
            let body = '';
            if (messageResult.payload.body?.data) {
              // Decode base64 body
              body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
            } else if (messageResult.payload.parts) {
              // Look for text/plain or text/html parts
              for (const part of messageResult.payload.parts) {
                if (part.mimeType === 'text/plain' && part.body?.data) {
                  body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
                  break;
                } else if (part.mimeType === 'text/html' && part.body?.data && !body) {
                  body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
                }
              }
            }

            emails.push({
              sender: from,
              receiver: to,
              time: date,
              subject: subject,
              body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''), // Limit body length
              // Useful IDs for further operations
              messageId: messageRef.id,
              threadId: messageResult.threadId || messageRef.threadId || '',
              labelIds: messageResult.labelIds || [],
              historyId: messageResult.historyId || '',
              internalDate: messageResult.internalDate || '',
              snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '')
            });
          }
        } catch (messageError) {
          console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError);
          // Continue with other messages
        }
      }

      return {
        emails,
        totalFound: emails.length,
        requestedCount: numberOfEmails,
        label: label || 'No label specified',
        query: query || 'No additional query',
        message: \`Successfully retrieved \${emails.length} emails\`,
        summary: \`Retrieved \${emails.length} Gmail emails\${label ? \` from \${label}\` : ''}\${query ? \` matching "\${query}"\` : ''}\`
      };

    } catch (error) {
      console.error('Gmail load error:', error);
      return {
        emails: [],
        totalFound: 0,
        error: String(error),
        message: \`Failed to load Gmail emails: \${error}\`,
        summary: \`Failed to load Gmail emails: \${error}\`
      };
    }
  },
});
\`\`\`

### Key Implementation Patterns

1. **Multiple API calls**: List messages first, then fetch details for each
2. **Proper error handling**: Try-catch blocks and graceful degradation
3. **Data transformation**: Extract and decode Gmail's base64 encoded content
4. **Pagination support**: Use maxResults and search queries
5. **Rich return format**: Include both raw data and user-friendly summaries

---

## 4) MCP Server Implementation (Gmail Example)

For building complete MCP servers with Pica integration, follow this structure:

### Project Structure
\`\`\`
gmail-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # Main MCP server
│   ├── tools/
│   │   ├── gmail.ts      # Gmail tool implementations
│   │   └── index.ts      # Tool registry
│   └── utils/
│       └── pica.ts       # Pica executor
└── dist/                 # Compiled output
\`\`\`

### package.json
\`\`\`json
{
  "name": "gmail-mcp-server",
  "version": "1.0.0",
  "description": "MCP server for Gmail integration via Pica",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}
\`\`\`

### src/index.ts (Main MCP Server)
\`\`\`ts
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { gmailTools } from './tools/gmail.js';

class GmailMCPServer {
  private server: Server;

  constructor() {
    this.server = new Server(
      {
        name: 'gmail-mcp-server',
        version: '1.0.0',
        description: 'MCP server for Gmail integration via Pica'
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );

    this.setupHandlers();
  }

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: 'load_gmail_emails',
            description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.',
            inputSchema: {
              type: 'object',
              properties: {
                label: {
                  type: 'string',
                  description: 'Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)'
                },
                numberOfEmails: {
                  type: 'number',
                  minimum: 1,
                  maximum: 50,
                  default: 10,
                  description: 'Number of emails to retrieve (1-50, default: 10)'
                },
                query: {
                  type: 'string',
                  description: 'Additional Gmail search query (e.g., "from:john@example.com", "subject:project")'
                }
              },
              required: []
            }
          }
        ]
      };
    });

    // Execute tools
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      try {
        switch (name) {
          case 'load_gmail_emails':
            return await gmailTools.loadEmails(args);
          default:
            throw new Error(\`Unknown tool: \${name}\`);
        }
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: \`Error executing \${name}: \${error instanceof Error ? error.message : String(error)}\`
            }
          ],
          isError: true
        };
      }
    });
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('Gmail MCP Server running on stdio');
  }
}

const server = new GmailMCPServer();
server.run().catch(console.error);
\`\`\`

### src/tools/gmail.ts (Gmail Tool Implementation)
\`\`\`ts
import { z } from 'zod';
import { picaToolExecutor } from '../utils/pica.js';

const LoadGmailEmailsSchema = z.object({
  label: z.string().optional(),
  numberOfEmails: z.number().min(1).max(50).default(10),
  query: z.string().optional()
});

export const gmailTools = {
  async loadEmails(args: any) {
    const input = LoadGmailEmailsSchema.parse(args);

    if (!process.env.PICA_API_KEY) {
      throw new Error('PICA_API_KEY environment variable is required');
    }

    const connectionKey = process.env.GMAIL_CONNECTION_KEY;

    try {
      // Build the search query
      let searchQuery = '';
      if (input.label) {
        searchQuery += \`label:\${input.label}\`;
      }
      if (input.query) {
        searchQuery += searchQuery ? \` \${input.query}\` : input.query;
      }

      // First, get the list of message IDs
      const queryParams = new URLSearchParams({
        maxResults: input.numberOfEmails.toString(),
        ...(searchQuery && { q: searchQuery })
      });

      const listMessagesResult = await picaToolExecutor(
        '/users/me/messages',
        'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ',
        connectionKey,
        { queryParams }
      );

      if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                emails: [],
                totalFound: 0,
                message: 'No emails found matching the criteria'
              }, null, 2)
            }
          ]
        };
      }

      // Get details for each message
      const emails = [];
      for (const messageRef of listMessagesResult.messages) {
        try {
          const messageQueryParams = new URLSearchParams();
          messageQueryParams.set('format', 'full');
          messageQueryParams.append('metadataHeaders', 'From');
          messageQueryParams.append('metadataHeaders', 'To');
          messageQueryParams.append('metadataHeaders', 'Subject');
          messageQueryParams.append('metadataHeaders', 'Date');

          const messageResult = await picaToolExecutor(
            \`/users/me/messages/\${messageRef.id}\`,
            'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw',
            connectionKey,
            { queryParams: messageQueryParams }
          );

          if (messageResult?.payload?.headers) {
            const headers = messageResult.payload.headers;

            const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || '';
            const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || '';
            const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || '';
            const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || '';

            // Extract and decode body content
            let body = '';
            if (messageResult.payload.body?.data) {
              body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
            } else if (messageResult.payload.parts) {
              for (const part of messageResult.payload.parts) {
                if (part.mimeType === 'text/plain' && part.body?.data) {
                  body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
                  break;
                } else if (part.mimeType === 'text/html' && part.body?.data && !body) {
                  body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
                }
              }
            }

            emails.push({
              sender: from,
              receiver: to,
              time: date,
              subject: subject,
              body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''),
              messageId: messageRef.id,
              threadId: messageResult.threadId || messageRef.threadId || '',
              snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '')
            });
          }
        } catch (messageError) {
          console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError);
        }
      }

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              emails,
              totalFound: emails.length,
              requestedCount: input.numberOfEmails,
              label: input.label || 'No label specified',
              query: input.query || 'No additional query',
              summary: \`Retrieved \${emails.length} Gmail emails\${input.label ? \` from \${input.label}\` : ''}\${input.query ? \` matching "\${input.query}"\` : ''}\`
            }, null, 2)
          }
        ]
      };
    } catch (error) {
      throw new Error(\`Failed to load Gmail emails: \${error instanceof Error ? error.message : String(error)}\`);
    }
  }
};
\`\`\`

### src/utils/pica.ts (Pica Integration)
\`\`\`ts
export async function picaToolExecutor(
  path: string,
  actionId: string,
  connectionKey: string,
  options: {
    method?: string;
    queryParams?: URLSearchParams;
    body?: any;
    contentType?: string;
  } = {}
) {
  const { method = 'GET', queryParams, body, contentType } = options;

  const baseUrl = 'https://api.picaos.com/v1/passthrough';
  const url = queryParams
    ? \`\${baseUrl}\${path}?\${queryParams.toString()}\`
    : \`\${baseUrl}\${path}\`;

  const headers: Record<string, string> = {
    'content-type': contentType || 'application/json',
    'x-pica-secret': process.env.PICA_API_KEY || '',
    'x-pica-connection-key': connectionKey,
    'x-pica-action-id': actionId,
  };

  const fetchOptions: RequestInit = { method, headers };

  if (body && method !== 'GET') {
    fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
  }

  const response = await fetch(url, fetchOptions);
  if (!response.ok) {
    const text = await response.text().catch(() => '');
    throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`);
  }
  return response.json().catch(() => ({}));
}
\`\`\`

### MCP Configuration
Add to your Claude Desktop config (\`~/Library/Application Support/Claude/claude_desktop_config.json\`):

\`\`\`json
{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp-server/dist/index.js"],
      "env": {
        "PICA_API_KEY": "your-pica-api-key"
      }
    }
  }
}
\`\`\`

---

## 5) Pagination, Rate Limits, and Errors

- Use fields defined by \`get_pica_action_knowledge\` (e.g., \`nextPageToken\`, \`cursor\`, \`page\`, \`limit\`).
- Loop until requested \`limit\` is reached or no \`next\` token remains.
- On \`429\`, backoff before retrying.
- Always return meaningful error messages and structured responses.

---

## 6) Security & Secrets

- Require \`PICA_API_KEY\` at runtime.
- Treat \`{PLATFORM}_CONNECTION_KEY\` as sensitive.
- No secrets in logs or errors.
- Validate all inputs with Zod schemas.

---

## 7) Project Detection (No Overwrite)

- If project markers exist (\`package.json\`, \`src/\`, \`.git\`, etc.), **do not** scaffold new project.
- Only add minimal new files for new tools or MCP endpoints.

---

## 8) Developer Experience

- Provide complete installation instructions:
  - \`npm install @modelcontextprotocol/sdk zod\`
  - \`npm install -D @types/node tsx typescript\`
- Build and run scripts:
  - \`"build": "tsc"\`
  - \`"dev": "tsx src/index.ts"\`
  - \`"start": "node dist/index.js"\`

---

## 9) Done Criteria

- Used Pica MCP discovery before coding
- MCP server/tool compiles and runs with \`PICA_API_KEY\` + \`{PLATFORM}_CONNECTION_KEY\`
- Tools are properly registered and callable
- Input/output validation with Zod schemas
- Error handling with meaningful responses
- Follows MCP protocol correctly
- Pagination & rate-limits handled if needed
- Minimal changes to existing project structure

---

You can verify setup by asking “What connections do I have in Pica?” - it should show your connections added above.

Benefits

Multi-Tenant Security

Enterprise-grade authenticationAuthKit handles OAuth flows, token management, and secure multi-tenant access

Automated Sync

Hourly email synchronizationBackground processes ensure your application always has the latest email data

Scalable Storage

Supabase real-time databasePostgreSQL-powered storage with RLS security and real-time subscriptions

AI-Ready Processing

BuildKit MCP integrationProcess emails through AI agents for classification, sentiment analysis, and automation

Advanced Features

Real-time Updates

WebSocket connections for live email updates
Instant notification system
Progressive sync with conflict resolution

Smart Processing

AI-powered email classification
Sentiment analysis and priority scoring
Automated response generation

Enterprise Scale

Multi-tenant architecture
Rate limiting and error handling
Comprehensive audit logging

Expand Your Email Automation

Ready to build more email integrations? Explore these additional capabilities:

Outlook Integration

Add Microsoft 365 and Outlook.com email sync with the same AuthKit flow

Slack Notifications

Send real-time notifications to Slack channels for important emails

AI Email Assistant

Build intelligent email responses and automated workflows with LLM integration

Analytics Dashboard

Create comprehensive email analytics and insights for business intelligence

🚀 Ready for more? Browse our catalog of 25,000+ actions across 150+ integrations to expand your email automation pipeline! Explore All Integrations →

Blog Posts

BuildKit

Use Cases

Build a Gmail Email Sync Automation

What we’ll do

Architecture Overview

Install the Pica MCP Server

Grab your API Key

Connect your accounts

Required Environment Variables

AuthKit Integration Setup

1. Install Dependencies

2. Supabase Database Schema

3. AuthKit Button Component

System Implementation

Set up a starter project

Add some rules for the LLMs to understand BuildKit

BuildKit Rules for Cursor

Benefits

Multi-Tenant Security

Automated Sync

Scalable Storage

AI-Ready Processing

Advanced Features

Real-time Updates

Smart Processing

Enterprise Scale

Expand Your Email Automation

Outlook Integration

Slack Notifications

AI Email Assistant

Analytics Dashboard

Blog Posts

BuildKit

Use Cases

​What we’ll do

​Architecture Overview

​Install the Pica MCP Server

Grab your API Key

​Connect your accounts

​Required Environment Variables

​AuthKit Integration Setup

​1. Install Dependencies

​2. Supabase Database Schema

​3. AuthKit Button Component

​System Implementation

​Set up a starter project

​Add some rules for the LLMs to understand BuildKit

BuildKit Rules for Cursor

​Benefits

Multi-Tenant Security

Automated Sync

Scalable Storage

AI-Ready Processing

​Advanced Features

Real-time Updates

Smart Processing

Enterprise Scale

​Expand Your Email Automation

Outlook Integration

Slack Notifications

AI Email Assistant

Analytics Dashboard

What we’ll do

Architecture Overview

Install the Pica MCP Server

Connect your accounts

Required Environment Variables

AuthKit Integration Setup

1. Install Dependencies

2. Supabase Database Schema

3. AuthKit Button Component

System Implementation

Set up a starter project

Add some rules for the LLMs to understand BuildKit

Benefits

Advanced Features

Expand Your Email Automation