Pica — Universal Integrations for AI

Pica gives your AI agent the ability to interact with 200+ third-party platforms — Gmail, Slack, HubSpot, Stripe, Notion, Linear, and more. The user has already installed the Pica CLI and run pica init, so the MCP server is configured and ready.

Your job: whenever the user needs to work with an external platform or integration, use Pica.

When This Skill Activates

Step 1: Check what's connected

Immediately call the list_pica_integrations MCP tool to see:

Which platforms are available
Which connections the user has active
The connection keys needed to execute actions

This tells you what the user can do right now and what's missing.

Step 2: Route the request

Connection exists for the platform the user needs → Use the MCP tool workflow below to fulfill the request.
Connection does NOT exist → Tell the user and offer to add it via pica add <platform>. See the "Adding a Missing Connection" section below.
User is browsing / exploring → Show them what's connected and suggest what they can do, or run pica platforms to browse everything available.

MCP Tool Workflow

This is the standard 4-step workflow for any integration task:

1. List integrations and connections

list_pica_integrations

Returns all available platforms and the user's active connections with their connection keys. Always start here to get the connection key you'll need.

2. Find the right action

get_pica_platform_actions(platform: "gmail")

Returns all available actions for a platform. Use the exact kebab-case platform name from step 1 (e.g., gmail, hubspot, google-calendar, ship-station).

3. Read the action docs (REQUIRED)

get_pica_action_knowledge(platform: "gmail", action_id: "<action_id>")

Returns full API documentation — parameters, requirements, caveats, and examples. You must call this before executing any action. Skipping this step will lead to malformed requests.

4. Execute the action

execute_pica_action(platform: "gmail", action: {_id, path, method}, connectionKey: "live::gmail::default::abc123", ...)

Performs the actual operation. Pass the connection key from step 1, the action details from step 2, and any required data/params from step 3.

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. Get from get_pica_platform_actions results.
Platform name: Kebab-case identifier (gmail, hubspot, google-calendar, ship-station). Get from list_pica_integrations.

Adding a Missing Connection

When the user needs a platform that isn't connected yet:

Tell the user the platform isn't connected and offer to add it.
Run:

pica add <platform>

This opens a browser for OAuth authentication. The CLI polls until the connection is live (up to 5 minutes).

Once connected, proceed with the MCP tool workflow above.

If the user isn't sure which platform they need, run:

pica platforms

This shows all 200+ available platforms organized by category. Supports -c <category> to filter (e.g., pica platforms -c "CRM").

CLI 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 available platforms

Aliases: pica ls = list, pica p = platforms.

All commands support --json for machine-readable output.

How it works

All API calls route through Pica's passthrough proxy, which injects auth credentials, handles rate limiting, and normalizes responses. Connection keys tell Pica which credentials to use — you never touch raw OAuth tokens.

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"

MCP tools not available

The agent needs to be restarted after MCP installation. For Claude Desktop, quit and reopen. For Claude Code, start a new session. If MCP was never installed, run pica init.

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

`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_. Run pica init to update.

Links

What	Where
Pica Dashboard	https://app.picaos.com
Get API key	https://app.picaos.com/settings/api-keys
Manage connections	https://app.picaos.com/connections
Browse integrations	https://app.picaos.com/tools
Documentation	https://docs.picaos.com

pica