Setup

Prerequisites

Before installing the MCP server, you’ll need:

Pica Account - Create a free account
Pica API Key - Get your API key from Settings > API Keys
Connected Integrations - Connect integrations from the Connections page
MCP-Compatible IDE - Claude Desktop, Cursor, Windsurf, or any MCP client

Installation

The easiest way to install the Pica MCP Server is via NPM:

npm install -g @picahq/mcp

Alternatively, you can use it directly with npx without installation:

npx @picahq/mcp

Other Installation Methods

Remote MCP Server
Smithery
Docker
From Source

Remote MCP Server

Install via remote MCP server

Install via Smithery for Claude Desktop:

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

Build and run with Docker:

# Build the image
docker build -t pica-mcp-server .

# Run the container
docker run -e PICA_SECRET=your_pica_secret_key \
  -e PICA_IDENTITY=user_123 \
  -e PICA_IDENTITY_TYPE=user \
  pica-mcp-server

PICA_IDENTITY and PICA_IDENTITY_TYPE are optional environment variables.

Clone and build from the GitHub repository:

# Clone the repository
git clone https://github.com/picahq/mcp.git
cd mcp

# Install dependencies
npm install

# Build the server
npm run build

Configuration

Set Your API Key

The MCP server requires your Pica API key to authenticate requests. Set it as an environment variable:

export PICA_SECRET=your_pica_secret_key

Get your API key from the Pica dashboard.

Optional: Identity Scoping

You can scope connections to a specific identity (e.g., a user, team, or organization) by setting these optional environment variables:

export PICA_IDENTITY=user_123
export PICA_IDENTITY_TYPE=user

Variable	Description	Values
`PICA_IDENTITY`	The identifier for the entity (e.g., user ID, team ID)	Any string
`PICA_IDENTITY_TYPE`	The type of identity	`user`, `team`, `organization`, `project`

When set, the MCP server will only return connections associated with the specified identity. This is useful for multi-tenant applications where you want to scope integrations to specific users or entities.

IDE Setup

Cursor
Windsurf

To use the MCP server in Cursor:

Open Cursor and go to Cursor Settings
Select MCP Settings from the menu
Add the following configuration to your MCP JSON file:

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

PICA_IDENTITY and PICA_IDENTITY_TYPE are optional. Only include them if you want to scope connections to a specific identity.

Save the file and restart Cursor

Testing in Cursor:Try asking Cursor:

“What connections do I have access to?”
“Show me all Gmail actions I can perform”
“Send an email using Gmail to hello@picaos.com”
“Build a React form component that sends emails with Gmail”

Configuration for Windsurf is similar to Cursor:

Open Windsurf settings
Navigate to the MCP configuration
Add the Pica MCP server configuration:

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

PICA_IDENTITY and PICA_IDENTITY_TYPE are optional. Only include them if you want to scope connections to a specific identity.

Examples

Once set up, you can use the MCP server for three main purposes:

Execute Actions
Generate Code
Get Insights

Direct Action Execution

Ask your AI to perform actions on integrated platforms:

Gmail - Read Emails

Get my last 5 emails from Gmail

The AI will use the MCP server to fetch your recent emails and display them.

Slack - Send Message

Send a message to #general channel in Slack: "Meeting in 10 minutes"

The AI will post the message to your Slack workspace.

Google Calendar - Create Event

Create a calendar event for tomorrow at 2pm titled "Product Review"

The AI will create the event in your Google Calendar.

Salesforce - Create Lead

Create a lead in Salesforce for John Doe at Acme Corp with email john@acme.com

The AI will create the lead in your Salesforce CRM.

Integration Code Generation

Ask your AI to build integration features:

Email Form Component

Prompt:

Create a React form component that sends emails using Gmail with Pica

What you get:

Complete React component with form fields
Gmail integration using Pica Passthrough API
Proper authentication handling
Error handling and validation

Dashboard with CRM Data

Prompt:

Build a dashboard that displays Salesforce leads with filtering options using Pica

What you get:

Dashboard component with data fetching
Integration with Salesforce API via Pica
Filter and search functionality
Responsive UI components

Invoice Management Table

Prompt:

Create a paginatable table for QuickBooks invoices with search and sort using Pica

What you get:

Table component with pagination
QuickBooks API integration
Search and sort capabilities
Export functionality

Multi-Channel Messaging

Prompt:

Build a form that posts messages to multiple Slack channels with scheduling using Pica

What you get:

Form with channel selection
Slack API integration
Message scheduling logic
Confirmation UI

Integration Knowledge

Ask questions about integrations and their capabilities:

List Available Connections

What connections do I have access to?

Shows all your connected integrations and their status.

Explore Platform Actions

What actions can I perform with Google Sheets?

Lists all available actions for Google Sheets with descriptions.

Understand Action Requirements

What parameters does the Gmail send message action require?

Provides detailed documentation about the action’s parameters, requirements, and usage.

Learn Authentication Methods

How do I authenticate with the Salesforce API using Pica?

Explains the authentication flow and requirements.

Advanced Configuration

Manual Installation

If you want more control over the installation:

# Clone the repository
git clone https://github.com/picahq/mcp.git
cd mcp

# Install dependencies
npm install

# Build the server
npm run build

# For development with auto-rebuild
npm run watch

Manual IDE Configuration:

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

PICA_IDENTITY and PICA_IDENTITY_TYPE are optional. Only include them if you want to scope connections to a specific identity.

Deploy to Vercel

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

Install dependencies including Vercel adapter:
```
npm install @vercel/mcp-adapter zod
```
Deploy to Vercel:
```
vercel
```
Set environment variables in Vercel:
- PICA_SECRET (required)
- PICA_IDENTITY (optional)
- PICA_IDENTITY_TYPE (optional)
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

See the DEPLOYMENT.md file in the repository for detailed instructions.

Troubleshooting

MCP Server Not Responding

Problem: The AI can’t connect to the MCP server.Solutions:

Verify your PICA_SECRET is set correctly in the configuration
Check that the MCP server is running (restart your IDE)
Ensure you have an active internet connection
Try running npx @picahq/mcp manually to test

Authentication Errors

Problem: Getting 401 or authentication errors.Solutions:

Verify your API key is valid at Settings > API Keys
Check that your integrations are connected at the Connections page
Ensure the API key has proper permissions

No Connections Available

Problem: The server reports no connections available.Solutions:

Connect integrations at app.picaos.com/connections
Verify connections are active and not expired
Re-authenticate if needed

Action Execution Fails

Problem: Actions fail to execute.Solutions:

Check the action knowledge first using get_pica_action_knowledge
Verify all required parameters are provided
Ensure your connection has proper permissions for the action
Check for rate limits or API-specific restrictions

Next Steps

Claude Desktop Setup

Specific setup guide for Claude Desktop

Browse Integrations

Explore all 200+ available integrations

API Reference

Learn about the underlying Pica APIs

GitHub Repository

View source code and contribute

Get Help

Contact Support

Have questions? Email us at support@picaos.com for assistance

Get Started

AuthKit

ToolKit

MCP Server

SaaS Integrations

BuildKit

Prerequisites

Installation

Other Installation Methods

Remote MCP Server

Configuration

Set Your API Key

Optional: Identity Scoping

IDE Setup

Examples

Direct Action Execution

Integration Code Generation

Integration Knowledge

Advanced Configuration

Manual Installation

Deploy to Vercel

Troubleshooting

Next Steps

Claude Desktop Setup

Browse Integrations

API Reference

GitHub Repository

Get Help

Contact Support

Get Started

AuthKit

ToolKit

MCP Server

SaaS Integrations

BuildKit

​Prerequisites

​Installation

​Other Installation Methods

Remote MCP Server

​Configuration

​Set Your API Key

​Optional: Identity Scoping

​IDE Setup

​Examples

​Direct Action Execution

​Integration Code Generation

​Integration Knowledge

​Advanced Configuration

​Manual Installation

​Deploy to Vercel

​Troubleshooting

​Next Steps

Claude Desktop Setup

Browse Integrations

API Reference

GitHub Repository

​Get Help

Contact Support

Prerequisites

Installation

Other Installation Methods

Configuration

Set Your API Key

Optional: Identity Scoping

IDE Setup

Examples

Direct Action Execution

Integration Code Generation

Integration Knowledge

Advanced Configuration

Manual Installation

Deploy to Vercel

Troubleshooting

Next Steps

Get Help