​

What is MCP?

Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop or Cursor, connect to external tools and data sources. It gives a clear and safe way for AI assistants to work with local services and APIs while keeping the user in control.

​

Pica MCP Server

Pica MCP Server is a server that enables seamless interaction with various third-party services through a standardized interface. This server provides direct access to platform integrations, actions, execution capabilities, and robust code generation capabilities.

​

Features

​

🔧 Tools

• list_pica_integrations - List all available platforms and your active connections
• get_pica_platform_actions - Get available actions for a specific platform
• get_pica_action_knowledge - Get detailed documentation for a specific action including parameters and usage
• execute_pica_action - Execute API actions with full parameter support

​

Key Capabilities

​

🔌 Platform Integration

• Connect to 100+ platforms through Pica
• Manage multiple connections per platform
• Access real-time connection status

​

🎯 Smart Intent Detection

• Execute actions immediately (e.g. “read my last gmail email”, “send a message to the slack channel #general”)
• Generate integration code (e.g. “build a form to send emails using gmail”, “create a UI for messaging”)
• Intelligent context handling

​

🔒 Enhanced Security

• Never exposes secrets in generated code
• Uses environment variables: PICA_SECRET, PICA_[PLATFORM]_CONNECTION_KEY
• Sanitized request configurations for production use

​

⚡ Direct Execution

• Execute actions directly through the MCP interface
• Support for all HTTP methods (GET, POST, PUT, DELETE, etc.)
• Handle form data, URL encoding, and JSON payloads
• Pass path variables, query parameters, and custom headers

​

🔒 Secure Authentication

• All requests authenticated through Pica’s secure proxy
• No need to manage individual platform API keys
• Environment variable configuration for security

​

Setup

Follow the guide below or watch this video for a quickstart:

​

Installation

npm install @picahq/mcp

​

Using npx

You can use this package directly with npx:

npx @picahq/mcp

Or install it globally:

npm install -g @picahq/mcp

​

Installing via Smithery

To install pica for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @picahq/mcp --client claude

​

Environment Setup

This server requires a Pica API key. Set the environment variable:

export PICA_SECRET=your_pica_secret_key

​

Client Integration

​

Using Claude Desktop

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%/Claude/claude_desktop_config.json

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

​

Using Cursor

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

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

​

Using Docker

Build the Docker Image:

docker build -t pica-mcp-server .

Run the Docker Container:

docker run -e PICA_SECRET=your_pica_secret_key pica-mcp-server

​

Docker with Claude Desktop

To use the Docker container with Claude Desktop, update your claude_desktop_config.json with:

{
  "mcpServers": {
    "pica-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "PICA_SECRET=YOUR_PICA_SECRET_KEY",
        "pica-mcp-server"
      ]
    }
  }
}

​

Manual Installation

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

​

Manual Claude Desktop Config

{
  "mcpServers": {
    "pica-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/pica-mcp-server/build/index.js"
      ],
      "env": {
        "PICA_SECRET": "YOUR_PICA_SECRET_KEY"
      }
    }
  }
}

Try asking Claude:

• What connections do I have access to?
• Send an email using gmail to hello@picaos.com
• What actions can I perform with google sheets?
• Create an event in my calendar
• List 5 users from my postgres users table
• Send a message in slack to the #general channel with today’s weather

​

Deploy to Vercel

You can deploy this MCP server to Vercel for remote access:

1. Install dependencies including Vercel adapter:

   Copy

   npm install @vercel/mcp-adapter zod
   

2. Deploy to Vercel:

   Copy

   vercel
   

3. Configure your MCP client to use the remote server:

   • For Cursor: https://your-project.vercel.app/api/mcp
   • For Claude/Cline: Use npx mcp-remote https://your-project.vercel.app/api/mcp

​

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

​

Examples for Inspiration

​

📋 Integration Code Generation

Build Email Form:

“Create me a React form component that can send emails using Gmail using Pica”

Linear Dashboard:

“Create a dashboard that displays Linear users and their assigned projects with filtering options using Pica”

QuickBooks Table:

“Build a paginatable table component that fetches and displays QuickBooks invoices with search and sort using Pica”

Slack Integration:

“Create a page with a form that can post messages to multiple Slack channels with message scheduling using Pica”

​

🚀 Direct Action Execution

Gmail Examples:

“Get my last 5 emails from Gmail using Pica”

Slack Examples:

“Send a slack message to #general channel: ‘Meeting in 10 minutes’ using Pica”

Shopify Examples:

“Get all products from my Shopify store using Pica”

​

API Reference

​

Tools

​

list_pica_integrations

List all available Pica integrations and platforms. Always call this tool first to discover available platforms and connections.

Parameters: None

Returns:

• Connected integrations grouped by platform
• Available platforms with descriptions
• Summary statistics
• Management links

​

get_pica_platform_actions

Get all available actions for a specific platform.

Parameters:

• platform (string, required): Platform name in kebab-case format (e.g., ‘ship-station’, ‘shopify’)

Returns:

• List of available actions with IDs and titles
• Platform-specific action count
• Next steps guidance

​

get_pica_action_knowledge

Get comprehensive documentation for a specific action. Must be called before execute_pica_action to understand requirements.

Parameters:

• action_id (string, required): Action ID from get_pica_platform_actions
• platform (string, required): Platform name in kebab-case format

Returns:

• Detailed action documentation
• Parameter requirements and structure
• API-specific guidance and caveats
• Usage examples and implementation notes

​

execute_pica_action

Execute a Pica action to perform operations on third-party platforms. Critical: Only call this when the user wants to execute an action, not when building applications.

Parameters:

• platform (string, required): Platform name
• action (object, required): Action object with _id, path, and method
• connectionKey (string, required): Connection key for the platform
• data (object, optional): Request body data
• pathVariables (object, optional): Variables to replace in the path
• queryParams (object, optional): Query parameters
• headers (object, optional): Additional headers
• isFormData (boolean, optional): Send as multipart/form-data
• isFormUrlEncoded (boolean, optional): Send as URL-encoded form data

Returns:

• requestConfig: Sanitized request configuration
• responseData: Actual API response from the platform

​

Error Handling

The server implements comprehensive error handling:

• ✅ Parameter validation for all tools
• ✅ Connection verification before execution
• ✅ Path variable validation and substitution
• ✅ Graceful handling of API failures
• ✅ Detailed error messages for debugging
• ✅ MCP-compliant error responses

​

Security

• 🔐 Single environment variable required: PICA_SECRET
• 🛡️ All requests authenticated through Pica’s secure proxy
• 🔒 No direct platform API key management needed
• 🚫 Secrets never exposed in responses
• ✅ Request configurations sanitized
• 🔍 Sensitive data filtered from logs
• 🛡️ Input validation and sanitization

​

Demo