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:

  ____  _
 |  _ \(_) ___ __ _
 | |_) | |/ __/ _` |
 |  __/| | (_| (_| |
 |_|   |_|\___\__,_|

 Welcome to Pica. Let's connect your agent to 200+ platforms.

Then follow the steps below.

Step 1: Check if Pica CLI is installed

Run this command to check:

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:

npm install -g @picahq/cli

After installation, verify it worked:

pica --version

If this still fails, check that the npm global bin directory is in the user's PATH. Common fix:

export PATH="$(npm prefix -g)/bin:$PATH"

Step 3: Run `pica init`

This is the core setup step. Run:

pica init

What `pica init` does

First run (no existing config):

Prompts for a Pica API key (get one at https://app.picaos.com/settings/api-keys)
Validates the key against the Pica API
Asks which AI agents to install the MCP server into (Claude Code, Claude Desktop, Cursor, Windsurf)
Asks for global or project-level installation
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):

Action	What it does
Update API key	Validates new key, re-installs MCP to all agents that have it
Install MCP to more agents	Shows only detected agents missing the MCP
Install MCP for this project	Creates project-level config files in cwd
Start fresh	Full setup flow from scratch

Init flags

Flag	Effect
`-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

Agent	Global config	Project 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:

Tool	What 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:

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:

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:

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

Command	Description
`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.

npm install -g @picahq/cli

If it's installed but not found, add the npm global bin to PATH:

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:

pica add <platform>

Or reconnect from the dashboard at https://app.picaos.com/connections.

Links

What	Where
Create account	https://app.picaos.com
Get API key	https://app.picaos.com/settings/api-keys
Add connections	https://app.picaos.com/connections
Browse integrations	https://app.picaos.com/tools
Documentation	https://docs.picaos.com

connect