Back to Details

pica

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pica — Universal Integrations for AI

Pica — 面向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.
Pica 可让你的AI Agent与200+第三方平台进行交互，包括Gmail、Slack、HubSpot、Stripe、Notion、Linear等。用户已完成Pica CLI的安装并执行了
pica init
，因此MCP服务器已配置就绪。
你的任务：每当用户需要与外部平台或集成功能交互时，使用Pica。

When This Skill Activates

触发此Skill的场景

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.
步骤1：查看已连接的平台
立即调用
list_pica_integrations
MCP工具，查看：
  • 可用的平台列表
  • 用户已激活的连接
  • 执行操作所需的连接密钥
这能让你了解用户当前可执行的操作以及缺失的配置。
步骤2：路由请求
  • 用户所需的平台已存在连接 → 使用下方的MCP工具工作流来完成请求。
  • 用户所需的平台未建立连接 → 告知用户并通过
    pica add <platform>
    帮助其添加连接。详情见下方“添加缺失的连接”章节。
  • 用户正在浏览/探索 → 展示已连接的平台并建议可执行的操作，或运行
    pica platforms
    查看所有可用平台。

MCP Tool Workflow

MCP工具工作流

This is the standard 4-step workflow for any integration task:
以下是处理任何集成任务的标准4步工作流：

1. List integrations and connections

1. 列出集成与连接

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.
list_pica_integrations
返回所有可用平台以及用户的活跃连接和对应的连接密钥。必须从此步骤开始，获取后续所需的连接密钥。

2. Find the right action

2. 找到对应的操作

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
).
get_pica_platform_actions(platform: "gmail")
返回指定平台的所有可用操作。使用步骤1中获取的短横线分隔格式（kebab-case）的平台名称（例如：
gmail
、
hubspot
、
google-calendar
、
ship-station
）。

3. Read the action docs (REQUIRED)

3. 查阅操作文档（必填）

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.
get_pica_action_knowledge(platform: "gmail", action_id: "<action_id>")
返回完整的API文档，包括参数、要求、注意事项和示例。执行任何操作前必须调用此工具，跳过此步骤会导致请求格式错误。

4. Execute the action

4. 执行操作

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.
execute_pica_action(platform: "gmail", action: {_id, path, method}, connectionKey: "live::gmail::default::abc123", ...)
执行实际操作。传入步骤1获取的连接密钥、步骤2获取的操作详情，以及步骤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
    .
  • 连接密钥：标识要使用的已认证连接。格式：
    live::gmail::default::abc123
    。可通过
    list_pica_integrations
    或
    pica list
    获取。
  • 操作ID：标识特定的API操作。可通过
    get_pica_platform_actions
    的结果获取。
  • 平台名称：短横线分隔格式的标识符（
    gmail
    、
    hubspot
    、
    google-calendar
    、
    ship-station
    ）。可通过
    list_pica_integrations
    获取。

Adding a Missing Connection

添加缺失的连接

When the user needs a platform that isn't connected yet:
  1. Tell the user the platform isn't connected and offer to add it.
  2. Run:
bash
pica add <platform>
This opens a browser for OAuth authentication. The CLI polls until the connection is live (up to 5 minutes).
  1. Once connected, proceed with the MCP tool workflow above.
If the user isn't sure which platform they need, run:
bash
pica platforms
This shows all 200+ available platforms organized by category. Supports 
-c <category>
to filter (e.g., 
pica platforms -c "CRM"
).
当用户需要的平台尚未连接时：
  1. 告知用户该平台未连接，并提供添加选项。
  2. 执行：
bash
pica add <platform>
此命令会打开浏览器进行OAuth认证。CLI会轮询直到连接生效（最长5分钟）。
  1. 连接完成后，按照上述MCP工具工作流继续操作。
若用户不确定需要哪个平台，可执行：
bash
pica platforms
此命令会按类别展示所有200+可用平台。支持
-c <category>
参数进行过滤（例如：
pica platforms -c "CRM"
）。

CLI Reference

CLI参考

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 available platforms
Aliases: 
pica ls
= list, 
pica p
= platforms.
All commands support 
--json
for machine-readable output.
命令描述
pica init
设置API密钥并安装MCP
pica add <platform>
通过OAuth连接平台
pica list
列出带密钥的连接
pica platforms
浏览可用平台
别名： 
pica ls
= list，
pica p
= platforms。
所有命令均支持
--json
参数以输出机器可读格式。

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.
所有API请求均通过Pica的直通代理路由，该代理会注入认证凭据、处理速率限制并标准化响应。连接密钥用于告知Pica使用哪些凭据——你无需直接接触原始OAuth令牌。

Troubleshooting

故障排查

pica: command not found

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"
Pica CLI未安装或未加入PATH。
bash
npm install -g @picahq/cli
若已安装但仍提示未找到，将npm全局bin目录添加到PATH：
bash
export PATH="$(npm prefix -g)/bin:$PATH"

MCP tools not available

MCP工具不可用

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
.
安装MCP后需重启Agent。对于Claude Desktop，需退出并重新打开；对于Claude Code，需开启新会话。若从未安装MCP，请执行
pica init
。

No connections found

No connections found

No apps have been connected yet. Run 
pica add gmail
(or any platform) to connect one.
尚未连接任何应用。执行
pica add gmail
（或其他平台）进行连接。

Connection shows 
failed
or 
degraded

连接显示
failed
或
degraded

The OAuth token expired or was revoked. Reconnect:
bash
pica add <platform>
Or reconnect from the dashboard at https://app.picaos.com/connections.
OAuth令牌已过期或被撤销。重新连接：
bash
pica add <platform>
或通过仪表盘https://app.picaos.com/connections重新连接。

Invalid API key

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.
密钥错误、过期或并非有效的Pica密钥。请前往https://app.picaos.com/settings/api-keys获取新密钥。密钥以`sk_live_`或`sk_test_`开头。执行`pica init`更新密钥。

Links

相关链接

WhatWhere
Pica Dashboardhttps://app.picaos.com
Get API keyhttps://app.picaos.com/settings/api-keys
Manage connectionshttps://app.picaos.com/connections
Browse integrationshttps://app.picaos.com/tools
Documentationhttps://docs.picaos.com
内容地址
Pica仪表盘https://app.picaos.com
获取API密钥https://app.picaos.com/settings/api-keys
管理连接https://app.picaos.com/connections
浏览集成https://app.picaos.com/tools
官方文档https://docs.picaos.com