> ## Documentation Index > Fetch the complete documentation index at: https://docs.picaos.com/llms.txt > Use this file to discover all available pages before exploring further. # Build an Automated Lead Qualification Agent > 🚀 Create an intelligent system that automatically processes incoming lead inquiry emails, qualifies them using AI, adds qualified leads to HubSpot CRM, and notifies your sales team via Slack for immediate follow-up. export const AddConnections = ({platforms}) => { if (!platforms) return null; return <> {platforms.map(platform => )} ; }; export const platformNames_1 = "Gmail, HubSpot, and Slack accounts" export const Header = ({size, text}) => { const Tag = `h${size}`; return {text}; }; export const platformNames_0 = "Gmail, HubSpot, and Slack accounts" export const projectType_0 = "MCP" ### What we'll do 1. Install the Pica MCP Server. 2. Connect your {platformNames_0}. 3. Set up a starter {projectType_0} project. 4. Add some rules for the LLMs to understand BuildKit. 5. Prompt the LLM to build your tool. ### 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: ```json MCP Settings theme={null} { "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. If you're on a paid Claude plan, you can add the server via the command line: ```bash Terminal Command theme={null} claude mcp add pica --env PICA_SECRET=your-pica-secret-key -- npx @picahq/mcp ``` Now you can run through the following: 1. Run claude in your terminal to start the Claude Code CLI. 2. Run `/mcp` to see your list of MCP servers. 3. See pica listed there! 4. Select it and go through the auth flow to enable the Pica MCP server in your claude code sessions! Replace `your-pica-secret-key` with your actual Pica Secret Key from the link below. You can add the Pica MCP server through the Windsurf UI or by editing the configuration file directly:
1. Open Windsurf Settings. 2. Under Cascade, find "Model Context Protocol Servers". 3. Select "Add Server" and paste the relevant snippet for your OS below.
Alternatively, edit your `~/.codeium/windsurf/mcp_config.json` file directly: ```json macOS/Linux theme={null} { "mcpServers": { "pica": { "command": "npx", "args": ["@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` ```json Windows theme={null} { "mcpServers": { "pica": { "command": "cmd", "args": ["/c", "npx", "@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` ```json Windows WSL theme={null} { "mcpServers": { "pica": { "command": "wsl", "args": ["npx", "@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` Replace `your-pica-secret-key` with your actual Pica Secret Key from the link below. Navigate to your Pica dashboard to access your API keys. ### Connect your accounts Now we need to connect your {platformNames_1} so we can test our tool after we build it. ### Required Environment Variables You'll need these connection keys in your environment: ```bash Environment Setup theme={null} GMAIL_CONNECTION_KEY=your_gmail_connection_key HUBSPOT_CONNECTION_KEY=your_hubspot_connection_key SLACK_CONNECTION_KEY=your_slack_connection_key OPENAI_API_KEY=your_openai_api_key PICA_API_KEY=your_pica_api_key ``` ### Key Actions Used This automation leverages 4 core actions across the three platforms: Fetches recent emails with the "Leads" label for processing Creates new contact records for qualified leads with extracted information Checks for existing contacts to prevent duplicates Sends formatted notifications to the sales team channel ### Using the System Once your system is set up, you can use this prompt to process lead inquiries: ``` Qualify today's lead inquiry emails from Gmail: for each email with the "Leads" label, extract sender details and qualify based on high intent signals (mentions budget over $5K, urgent timeline, specific product interest); if qualified with score >7/10, create a new contact in HubSpot with extracted information and lead source "Email Inquiry"; then send a Slack notification to #sales-leads channel with lead summary, qualification reasoning, and HubSpot contact link. Only process emails from the last 24 hours. ``` ### Qualification Criteria The AI evaluates leads based on these factors: * Mentions specific budget amount over \$5,000 * Indicates urgent timeline (immediate, ASAP, this week/month) * References specific products/services by name * Includes company name and professional email domain * Mentions existing pain points or current solutions * General budget discussion without specific amounts * Mentions timeline within 3-6 months * Professional language and detailed inquiry * Includes contact phone number * References competitors or market research * Generic inquiry templates * No timeline mentioned * Personal email addresses only * Vague or very brief messages * No budget or price sensitivity mentioned ### Set up a starter project Choose your preferred framework and follow the setup steps to get your starter project up and running. 1. Clone and install dependencies. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-vercel-ai-starter.git && cd buildkit-vercel-ai-starter ``` ```bash Install Dependencies theme={null} npm install ``` 2. Set up environment variables. ```text .env.local (root directory) theme={null} OPENAI_API_KEY=your_openai_api_key_here ``` 3. Run the development server. ```bash Start Server theme={null} npm run dev ``` 4. Open your browser.

Navigate to [http://localhost:3000](http://localhost:3000) to see the chat interface.

 1. Clone the repository. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-langchain-starter.git && cd buildkit-langchain-starter ``` 2. Create & activate virtual environment. ```bash macOS/Linux theme={null} python -m venv venv && source venv/bin/activate ``` ```bash Windows theme={null} python -m venv venv && venv\Scripts\activate ``` 3. Install dependencies. ```bash Install Requirements theme={null} pip install -r requirements.txt ``` 4. Configure OpenAI ```bash Copy Environment File theme={null} cp .env.example .env ``` 5. Set up environment variables. ```text .env (root directory) theme={null} OPENAI_API_KEY=your_openai_api_key_here ``` 6. Run the backend server. ```bash Start Server theme={null} python -m src.backend ``` 7. Open your browser.

Visit [http://localhost:8000](http://localhost:8000) to use the chat interface.

 Set up the MCP Server starter for building custom Model Context Protocol servers: 1. Clone the repository. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-mcp-starter.git && cd buildkit-mcp-starter ``` 2. Install dependencies. ```bash Install Dependencies theme={null} Install Dependencies ``` 3. Build the project. ```bash Build Project theme={null} npm run build ``` 4. Run the server. ```bash Development Mode theme={null} npm run dev ```

The server will start and listen for MCP requests.You should see:

`MCP Server running on http://localhost:3000/mcp`

5. Test with MCP Inspector.

The easiest way to test your MCP server is using the official MCP Inspector.

```bash Start Inspector theme={null} npx @modelcontextprotocol/inspector ``` This will: * Start the MCP Inspector proxy server. * Open your browser automatically. * Show you the Inspector interface. ### Add some rules for the LLMs to understand BuildKit
Copy the rules content and paste them into `.cursor/rules/buildkit.mdc` in the root of your project. ```markdown BuildKit Rules for Cursor expandable theme={null} --- 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 = { '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 = { '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 --- ```
Copy instructions for Claude to use BuildKit rules. Paste these into a file named CLAUDE.md in the root of your project. ```markdown BuildKit Rules for Claude Code expandable theme={null} 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. Before you write ANY code you read ALL of buildkit-rules.md to understand how to use BuildKit in your code. ```
Copy the rules content and paste them into `buildkit-rules.md` in the root of your project. ```markdown BuildKit Rules for Claude Code expandable theme={null} --- 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 = { '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 = { '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 --- ```
Copy the rules content and paste them into `.windsurf/rules/buildkit.md` in the root of your project. ```markdown BuildKit Rules for Windsurf expandable theme={null} --- trigger: always_on description: How to use BuildKit globs: --- # 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. **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) 7. **Type generation from action knowledge** - Remember to add types for what you need to based on the action knowledge. --- ## 1) Discovery Order Call these **Pica MCP tools** (if available): ### Step 1: List available integrations \`\`\` get_pica_integrations() \`\`\` ### Step 2: Get available actions for a platform \`\`\` get_pica_platform_actions(platform_name) // e.g., platform_name = "gmail" | "hubspot" | "asana" | ... \`\`\` ### Step 3: Get action knowledge for implementation \`\`\` get_pica_action_knowledge(platform_name, action_id) // Gets: JSON schema, auth requirements, path template, rate limits \`\`\` --- ## 2) Vercel AI SDK Tool Building After discovering actions via Pica MCP, create tools like this: \`\`\`typescript import { tool } from 'ai'; import { z } from 'zod'; // picaToolExecutor - the universal Pica caller const picaToolExecutor = async (args) => { const { PICA_API_KEY } = process.env; if (!PICA_API_KEY) throw new Error('PICA_API_KEY not found'); const { platform, path, method, query, body, contentType, connectionKey } = args; const url = new URL(\`https://app.picaos.com/api/v1/integrations/\${platform}/actions\`); if (query) { Object.entries(query).forEach(([k, v]) => url.searchParams.append(k, v)); } const headers = { 'Authorization': \`Bearer \${PICA_API_KEY}\`, 'X-Connection-Key': connectionKey, }; if (contentType) headers['Content-Type'] = contentType; const config = { method, headers }; if (body && method !== 'GET') { config.body = contentType?.includes('json') ? JSON.stringify(body) : body; } const response = await fetch(url, config); if (!response.ok) { throw new Error(\`Pica API error: \${response.status} \${response.statusText}\`); } return response.json(); }; // Example tool using action knowledge export const gmailTool = tool({ description: 'Fetch unread Gmail emails using Pica', parameters: z.object({ maxResults: z.number().optional().default(10), }), execute: async ({ maxResults }) => { return await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: maxResults.toString() }, connectionKey: process.env.GMAIL_CONNECTION_KEY, }); }, }); \`\`\` --- ## 3) LangChain Tool Building \`\`\`typescript import { DynamicStructuredTool } from "@langchain/core/tools"; import { z } from "zod"; // Same picaToolExecutor as above... export const gmailLangChainTool = new DynamicStructuredTool({ name: "fetch_gmail_emails", description: "Fetch unread Gmail emails using Pica BuildKit", schema: z.object({ maxResults: z.number().optional().default(10), }), func: async ({ maxResults }) => { const result = await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: maxResults.toString() }, connectionKey: process.env.GMAIL_CONNECTION_KEY, }); return JSON.stringify(result); }, }); \`\`\` --- ## 4) MCP Server Building When building MCP servers, scaffold complete projects: ### File Structure \`\`\` my-integration-mcp/ ├── package.json ├── src/ │ └── index.ts ├── build/ └── README.md \`\`\` ### package.json template \`\`\`json { "name": "my-integration-mcp", "version": "1.0.0", "type": "module", "main": "build/index.js", "scripts": { "build": "tsc", "prepare": "npm run build" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0" }, "devDependencies": { "typescript": "^5.0.0", "@types/node": "^20.0.0" } } \`\`\` ### src/index.ts template \`\`\`typescript #!/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'; // Same picaToolExecutor as above... const server = new Server( { name: 'my-integration-mcp', version: '1.0.0' }, { capabilities: { tools: {} } } ); server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'fetch_emails', description: 'Fetch emails from the integration', inputSchema: { type: 'object', properties: { maxResults: { type: 'number', description: 'Max results', default: 10 } }, required: [] } } ] }; }); server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; switch (name) { case 'fetch_emails': return { content: [{ type: 'text', text: JSON.stringify(await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: args.maxResults?.toString() || '10' }, connectionKey: process.env.GMAIL_CONNECTION_KEY, })) }] }; default: throw new Error(\`Unknown tool: \${name}\`); } }); async function main() { const transport = new StdioServerTransport(); await server.connect(transport); } main().catch(console.error); \`\`\` ### tsconfig.json \`\`\`json { "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "node", "outDir": "./build", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"] } \`\`\` --- ## 5) Testing Your Integration Always provide testing steps: 1. Set environment variables 2. Test connection 3. Verify tool responses 4. Check error handling --- ## 6) Final Requirements Every integration you build must have: - Environment validation (\`PICA_API_KEY\`) - Connection key validation - Proper 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. ### Prompt the LLM to build your tool Copy this prompt to build the MCP Lead Qualification Agent: ```markdown MCP Agent Prompt expandable theme={null} # MCP Agent Prompt (Automated Lead Qualification Agent) Create a comprehensive MCP agent with multiple tools for automated lead qualification using BuildKit and Pica integrations. The agent should: TOOLS NEEDED: 1. fetchLeadEmails - Fetch Gmail emails from last 24 hours with "Leads" label 2. extractLeadInformation - Extract structured lead data (name, email, company, phone, budget, timeline) from email content 3. qualifyLeadWithAI - Use AI to score leads based on qualification criteria (budget, timeline, intent, company size) 4. checkExistingContact - Search HubSpot for existing contacts to prevent duplicates 5. createHubSpotContact - Create new contact in HubSpot with extracted lead information 6. sendSlackNotification - Send formatted notification to sales team with lead details and HubSpot link QUALIFICATION SCORING CRITERIA: - High-Value Indicators (+2-3 points each): * Mentions specific budget over $5,000 * Indicates urgent timeline (immediate, ASAP, this week/month) * References specific products/services by name * Includes company name and professional email domain * Mentions existing pain points or current solutions - Medium-Value Indicators (+1-2 points each): * General budget discussion without specific amounts * Mentions timeline within 3-6 months * Professional language and detailed inquiry * Includes contact phone number * References competitors or market research - Low-Value Indicators (0-1 points each): * Generic inquiry templates * No timeline mentioned * Personal email addresses only * Vague or very brief messages * No budget or price sensitivity mentioned HUBSPOT CONTACT STRUCTURE: - First Name - Last Name - Email (Primary) - Company Name - Phone Number - Lead Source: "Email Inquiry" - Lead Status: "New" - Lead Score: (AI qualification score 1-10) - Notes: (AI qualification reasoning) SLACK NOTIFICATION FORMAT: 🎯 **New Qualified Lead** (Score: X/10) **Contact:** [Name] at [Company] **Email:** [email] | **Phone:** [phone] **Budget:** [extracted budget info] **Timeline:** [extracted timeline] **Qualification Reasoning:** [AI explanation of why this lead scored X/10] **Next Actions:** - [ ] Review HubSpot contact: [HubSpot URL] - [ ] Send personalized follow-up within 2 hours - [ ] Schedule discovery call if appropriate **Original Message:** [First 200 characters of email...] WORKFLOW: 1. Fetch emails with "Leads" label from last 24 hours 2. For each email: - Extract lead information (name, email, company, phone, budget indicators, timeline) - Score lead using AI qualification criteria (1-10 scale) - If score >= 7/10: * Check HubSpot for existing contact by email * If new contact: Create HubSpot contact with extracted data * If existing: Update with new lead score and notes * Send Slack notification to #sales-leads channel - If score < 7/10: Log as unqualified lead for review ERROR HANDLING: - Skip emails that can't be parsed or are clearly spam - Handle duplicate contacts gracefully - Retry failed API calls up to 3 times - Log all actions for audit trail CUSTOMIZATION OPTIONS: - Adjustable qualification score threshold (default: 7/10) - Configurable Slack channel (#sales-leads) - Custom HubSpot properties based on business needs - Flexible email label filtering ("Leads", "Inquiries", etc.) The agent should process all qualifying leads efficiently while maintaining data quality and providing actionable insights to the sales team. ``` Copy this prompt to build the Vercel AI SDK tool: ```markdown Vercel AI SDK Agent Prompt expandable theme={null} # Vercel AI SDK Agent Prompt (Automated Lead Qualification Agent) Create a comprehensive Vercel AI SDK agent with multiple tools for automated lead qualification using BuildKit and Pica integrations. The agent should: TOOLS NEEDED: 1. fetchLeadEmails - Fetch Gmail emails from last 24 hours with "Leads" label 2. extractLeadInformation - Extract structured lead data from email content 3. qualifyLeadWithAI - Score leads using AI qualification criteria 4. checkExistingContact - Search HubSpot for existing contacts 5. createHubSpotContact - Create new contact in HubSpot 6. sendSlackNotification - Send formatted notification to sales team QUALIFICATION SCORING (1-10 scale): - Budget mentioned over $5K: +3 points - Urgent timeline (immediate/ASAP): +3 points - Specific product interest: +2 points - Professional email domain: +2 points - Detailed inquiry: +2 points - Company name provided: +1 point - Phone number included: +1 point WORKFLOW: 1. Fetch recent emails with "Leads" label 2. Extract and score each lead using AI 3. For qualified leads (score >= 7): - Check for existing HubSpot contact - Create new contact if needed - Send Slack notification with lead details 4. Log all actions for audit trail The agent should qualify leads quickly and route high-value prospects to the sales team immediately. ``` Copy this prompt to build the LangChain tool: ```markdown LangChain Agent Prompt expandable theme={null} # LangChain Agent Prompt (Automated Lead Qualification Agent) Create a LangChain agent with tools for automated lead qualification using BuildKit and Pica integrations: TOOLS NEEDED: 1. GmailLeadFetcher - Retrieve emails with "Leads" label 2. LeadQualifier - AI-powered lead scoring and extraction 3. HubSpotContactManager - Create/update contacts 4. SlackNotifier - Send team notifications QUALIFICATION LOGIC: - High intent signals: budget mentions, urgency, specific needs - Score threshold: 7/10 for qualification - Automatic CRM entry for qualified leads - Real-time Slack alerts for sales team WORKFLOW: Email → AI Qualification → HubSpot Contact → Slack Alert The agent should streamline lead processing and ensure no qualified prospects are missed. ``` ## Benefits **Process leads within minutes** Automatically qualify and route hot leads to your sales team before competitors respond **AI-powered scoring system** Eliminate human bias with standardized qualification criteria applied to every lead **Complete lead capture** Never miss a qualified lead with automated processing and CRM integration **Focus on high-value prospects** Pre-qualified leads with context help sales teams prioritize their outreach efforts ## Advanced Customization Ready to enhance your lead qualification? Consider these additions: Set up HubSpot workflows to trigger additional actions based on lead scores Automatically book discovery calls for high-scoring leads using Calendly Trigger personalized email sequences in HubSpot based on lead qualification Enhance contact records with additional data from LinkedIn or company databases 🚀 **Ready for more?** Browse our catalog of 25,000+ actions across 200+ integrations to expand your lead qualification pipeline! [Explore All Integrations →](https://app.picaos.com/tools)