connect

Original：🇺🇸 English
Translated

Set up the Pica CLI and MCP server so AI agents can interact with Gmail, Slack, HubSpot, Stripe, and 200+ platforms. Handles installation, initialization, and first connection.

11installs
Sourcepicahq/skills
Added on

NPX Install

npx skill4agent add picahq/skills connect

Tags

Translated version includes tags in frontmatter
ai-agent-integrationpica-cli-setupmcp-server-configurationplatform-connectionintegration-workflow

SKILL.md Content

View Translation Comparison →

Pica Connect

Set up the Pica CLI and MCP server so your AI agent can send emails, post to Slack, update CRMs, and interact with 200+ platforms.

When This Skill Activates

When the skill activates, start by printing this welcome message:
██████████████   ██████   ██████████████   ██████████████
██████████████   ██████   ██████████████   ██████████████
█████    █████   ██████   █████            █████    █████
█████    █████   ██████   █████            █████    █████
██████████████   ██████   █████            ██████████████
██████████████   ██████   █████            ██████████████
█████            ██████   █████            █████    █████
█████            ██████   █████            █████    █████
█████            ██████   ██████████████   █████    █████
█████            ██████   ██████████████   █████    █████

U N I V E R S A L   I N T E G R A T I O N S   F O R   A I
Then follow the steps below.

Step 1: Check if Pica CLI is installed

Run this command to check:
bash
pica --version
If the command succeeds (prints a version number): Pica is installed. Skip to Step 3.
If the command fails (
command not found
): Continue to Step 2.

Step 2: Install Pica CLI

Install globally via npm:
bash
npm install -g @picahq/cli
After installation, verify it worked:
bash
pica --version
If this still fails, check that the npm global bin directory is in the user's PATH. Common fix:
bash
export PATH="$(npm prefix -g)/bin:$PATH"

Step 3: Run 
pica init

This is the core setup step. Run:
bash
pica init

What 
pica init
does

First run (no existing config):
  1. Prompts for a Pica API key (get one at https://app.picaos.com/settings/api-keys)
  2. Validates the key against the Pica API
  3. Asks which AI agents to install the MCP server into (Claude Code, Claude Desktop, Cursor, Windsurf)
  4. Asks for global or project-level installation
  5. Writes the MCP config so the agent gets access to integration tools
Subsequent runs (config already exists):
Shows a status dashboard with the current API key, config path, and per-agent MCP installation status:
  Current Setup
  ──────────────────────────────────────────
  API Key:  sk_test_...9j-Y
  Config:   ~/.pica/config.json

  Agent           Global  Project
  ──────────────  ──────  ───────
  Claude Code     ● yes   ● yes
  Claude Desktop  ● yes   -
  Cursor          ○ no    ○ no
  Windsurf        -       -

  - = not detected on this machine
Then offers targeted actions (only relevant options appear):
ActionWhat it does
Update API keyValidates new key, re-installs MCP to all agents that have it
Install MCP to more agentsShows only detected agents missing the MCP
Install MCP for this projectCreates project-level config files in cwd
Start freshFull setup flow from scratch

Init flags

FlagEffect
-y, --yes
Skip confirmations
-g, --global
Install MCP globally (available in all projects)
-p, --project
Install MCP for this project only

Where MCP configs are written

AgentGlobal configProject config
Claude Code
~/.claude.json
.mcp.json
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json
n/a
Cursor
~/.cursor/mcp.json
.cursor/mcp.json
Windsurf
~/.codeium/windsurf/mcp_config.json
n/a
After 
pica init
completes, the agent will have access to these MCP tools:
ToolWhat it does
list_pica_integrations
List all platforms and active connections
search_pica_platform_actions
Search for actions on a platform
get_pica_action_knowledge
Get full API docs for an action
execute_pica_action
Execute an action on a connected platform

Step 4: First connection

After init completes, prompt the user:
Pica is set up! Your agent now has access to 200+ integrations.

What would you like to do first?
  1. Connect a platform (e.g. Gmail, Slack, HubSpot)
  2. Browse available platforms
  3. Skip for now
If option 1: Ask which platform, then run:
bash
pica add <platform>
This opens a browser for OAuth. The CLI polls until the connection is live. Common first connections: 
gmail
, 
slack
, 
google-calendar
, 
hubspot
, 
notion
, 
linear
.
If option 2: Run:
bash
pica platforms
This shows all 200+ available platforms with categories.
If option 3: Let them know they can come back anytime:
No problem. When you're ready:
  pica add gmail       - Connect Gmail
  pica platforms       - Browse all platforms
  pica list            - See your connections

Step 5: Verify and use

Once a connection is added, verify it:
bash
pica list
Output shows connection status and keys:
  ● gmail      operational
    live::gmail::default::abc123
If MCP tools are available, show the user what they can do:
You're all set! Try asking me to:
  "Send an email to sarah@example.com about the project update"
  "Post the release notes to #product in Slack"
  "Create a Linear issue for the login bug"
  "Check my calendar for tomorrow"

Using MCP tools (after setup)

Once the MCP is installed and connections are live, this is the standard workflow for any integration task:
1. list_pica_integrations          -> get connection keys and platform names
2. search_pica_platform_actions    -> find the right action
3. get_pica_action_knowledge       -> read the docs (REQUIRED before execute)
4. execute_pica_action             -> do the thing

Key concepts

  • Connection key: Identifies which authenticated connection to use. Format: 
    live::gmail::default::abc123
    . Get from 
    list_pica_integrations
    or 
    pica list
    .
  • Action ID: Identifies a specific API action. Starts with 
    conn_mod_def::
    . Get from search results.
  • Platform name: Kebab-case identifier (
    gmail
    , 
    hubspot
    , 
    google-calendar
    , 
    ship-station
    ). Get from 
    list_pica_integrations
    .

CLI quick reference

CommandDescription
pica init
Set up API key and install MCP
pica add <platform>
Connect a platform via OAuth
pica list
List connections with keys
pica platforms
Browse all 200+ platforms
pica search <platform> [query]
Search for actions
pica actions knowledge <id>
Get API docs for an action
pica exec <id>
Execute an action
Aliases: 
pica ls
= list, 
pica p
= platforms, 
pica a k
= actions knowledge, 
pica a x
= actions execute.
All commands support 
--json
for machine-readable output.

Troubleshooting

pica: command not found

Pica CLI is not installed or not in PATH.
bash
npm install -g @picahq/cli
If it's installed but not found, add the npm global bin to PATH:
bash
export PATH="$(npm prefix -g)/bin:$PATH"

Invalid API key

The key is wrong, expired, or not a valid Pica key. Get a new one at https://app.picaos.com/settings/api-keys. Keys start with 
sk_live_
or 
sk_test_
.

MCP tools not available after init

The agent needs to be restarted after MCP installation. For Claude Desktop, quit and reopen. For Claude Code, start a new session.

No connections found

No apps have been connected yet. Run 
pica add gmail
(or any platform) to connect one.

Connection shows 
failed
or 
degraded

The OAuth token expired or was revoked. Reconnect:
bash
pica add <platform>
Or reconnect from the dashboard at https://app.picaos.com/connections.

Links

WhatWhere
Create accounthttps://app.picaos.com
Get API keyhttps://app.picaos.com/settings/api-keys
Add connectionshttps://app.picaos.com/connections
Browse integrationshttps://app.picaos.com/tools
Documentationhttps://docs.picaos.com