build-product-integrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Integration

应用集成

Build apps that integrate with external services via Membrane. Uses the Membrane CLI.

Use this skill when you need to add third-party integrations to a product — connecting customers to external apps, running actions on their behalf, syncing data, or providing AI agent tools.

通过Membrane构建可与外部服务集成的应用，使用Membrane CLI工具。

当你需要为产品添加第三方集成功能时使用本技能——帮助客户连接外部应用、代表客户执行操作、同步数据或提供AI Agent工具。

How Membrane Works

Membrane工作原理

Membrane is an integration engine. You define what your app needs (which external apps, what operations, what data) and Membrane handles authentication, API calls, and data transformation.

Membrane是一款集成引擎。你只需定义应用的需求（需要连接哪些外部应用、执行哪些操作、处理哪些数据），Membrane会负责身份验证、API调用和数据转换。

Core Concepts

核心概念

Workspace — your project in Membrane. Contains all integrations, connectors, and configuration for your product.

Customer — a user or organization in your product. Each customer gets their own set of connections and integration state. Identified by a unique ID you choose (e.g. your user/org ID).

Connector — a pre-built adapter for an external app (e.g. Slack, HubSpot). Handles authentication (OAuth, API keys), API client setup, and connection testing. Membrane has connectors for thousands of apps — if one doesn't exist, Membrane Agent can build it.

Integration — the relationship between your product and an external app. Defined in your workspace, it groups connectors, actions, data collections, and flows for a specific app.

Connection — an authenticated link between a customer and an external app. Created when a customer goes through the OAuth/auth flow. Contains credentials managed by Membrane.

Action — a single operation on a connected app (e.g. "Send message", "Create task", "List contacts"). Has typed

inputSchema

and

outputSchema

. Can be run via API or used as AI agent tools.

Data Collection — a consistent API for working with external app data like a database table. Supports list, find, search, create, update, delete operations.

Flow — multi-step async logic triggered by events, schedules, or API calls. Composed of trigger, function, and control nodes.

工作区（Workspace）——你在Membrane中的项目，包含产品的所有集成、连接器和配置。

客户（Customer）——你的产品中的用户或组织。每个客户都有自己的连接集和集成状态，由你指定的唯一ID（如用户/组织ID）标识。

连接器（Connector）——针对外部应用的预构建适配器（如Slack、HubSpot），负责处理身份验证（OAuth、API密钥）、API客户端设置和连接测试。Membrane拥有数千个应用的连接器——如果所需连接器不存在，Membrane Agent可以自动构建。

集成（Integration）——你的产品与某一外部应用之间的关联关系，在工作区中定义，包含针对该应用的连接器、操作、数据集合和流程。

连接（Connection）——客户与外部应用之间的已验证链接，当客户完成OAuth/身份验证流程后创建，包含由Membrane管理的凭据。

操作（Action）——对已连接应用执行的单个操作（如“发送消息”“创建任务”“列出联系人”），拥有类型化的

inputSchema

和

outputSchema

，可通过API调用或作为AI Agent工具使用。

数据集合（Data Collection）——用于处理外部应用数据的统一API，类似数据库表，支持列表、查找、搜索、创建、更新、删除操作。

流程（Flow）——由事件、计划或API调用触发的多步异步逻辑，由触发器、函数和控制节点组成。

Element Layers

元素层级

Membrane elements exist at three layers:

Universal — work across multiple external apps (no specific integration). Example: a "Create Task" action that works with any task management app.
Integration — specific to one external app (has
```
integrationId
```
). Example: a "Create Jira Issue" action.
Connection — specific to a customer's connection (has
```
connectionId
```
). Can customize integration-level elements per customer.

Integration-level elements need implementations per integration. Connection-level elements can override/customize integration-level defaults.

Membrane元素分为三个层级：

通用层（Universal）——可跨多个外部应用工作（不绑定特定集成），例如适用于任意任务管理应用的“创建任务”操作。
集成层（Integration）——绑定单个外部应用（包含
```
integrationId
```
），例如“创建Jira问题”操作。
连接层（Connection）——绑定客户的特定连接（包含
```
connectionId
```
），可针对单个客户自定义集成层元素。

集成层元素需要为每个集成单独实现，连接层元素可覆盖或自定义集成层的默认设置。

Authentication Architecture

身份验证架构

Membrane uses JWT tokens for API access:

Workspace Key — identifies your workspace (set as JWT
```
iss
```
claim)
Workspace Secret — used to sign tokens (never expose to frontend)
Customer Token — JWT containing workspace key + customer ID, generated on your backend, used by frontend SDKs and API calls

External app credentials (OAuth tokens, API keys) are managed by Membrane — your app never handles them directly.

Membrane使用JWT令牌进行API访问：

工作区密钥（Workspace Key）——标识你的工作区（作为JWT的
```
iss
```
声明）
工作区密钥（Workspace Secret）——用于签名令牌（绝不能暴露给前端）
客户令牌（Customer Token）——包含工作区密钥和客户ID的JWT，由你的后端生成，供前端SDK和API调用使用

外部应用的凭据（OAuth令牌、API密钥）由Membrane管理——你的应用无需直接处理这些凭据。

Standard Workflow: Search → Use → Delegate

标准工作流：搜索 → 使用 → 委托

Always follow this pattern when working with Membrane:

Search for what you need — use intent search to find actions, connectors, or integrations
Use it if it exists — run the action, connect with the connector, etc.
Delegate to Membrane Agent if it doesn't exist — create an agent session to build the missing element

Example: User wants to list Slack channels

bash

undefined

使用Membrane时请始终遵循以下模式：

搜索所需功能——通过意图搜索查找操作、连接器或集成
若存在则直接使用——执行操作、使用连接器等
若不存在则委托给Membrane Agent——创建Agent会话来构建缺失的元素

示例：用户希望列出Slack频道

bash

undefined

Step 1: Search for a "list channels" action

步骤1：搜索“列出频道”操作

npx @membranehq/cli action list --connectionId <slack-conn-id> --intent "list channels" --limit 5 --json

Step 2: If found, run it

步骤2：若找到则执行

npx @membranehq/cli action run <actionId> --connectionId <slack-conn-id> --json

Step 3: If NOT found, delegate to Membrane Agent

步骤3：若未找到则委托给Membrane Agent

npx @membranehq/cli agent-session create --agent action-building --message "Create an action to list Slack channels for connection <slack-conn-id>" --json npx @membranehq/cli agent-session get <sessionId> --wait --json

Then search again and run the newly created action

然后再次搜索并运行新创建的操作


Example: User wants to add a new app (e.g. Notion)

```bash


示例：用户希望添加新应用（如Notion）

```bash

Step 1: Search for existing Notion connector

步骤1：搜索现有Notion连接器

npx @membranehq/cli search notion --elementType connector --json

Step 2: If found, create a connection

步骤2：若找到则创建连接

npx @membranehq/cli connect --connectorId <connectorId>

Step 3: If NOT found, delegate to Membrane Agent

步骤3：若未找到则委托给Membrane Agent

npx @membranehq/cli agent-session create --agent connection-building --message "Build a connector for Notion (https://notion.so)" --json npx @membranehq/cli agent-session get <sessionId> --wait --json

Then create a connection with the new connector

然后使用新创建的连接器创建连接


**This pattern applies to everything in Membrane.** When an element (action, connector, data collection, flow) doesn't exist, always delegate to Membrane Agent to build it — never try to build it yourself.


**此模式适用于Membrane的所有功能**。当某个元素（操作、连接器、数据集合、流程）不存在时，请始终委托给Membrane Agent来构建——不要自行构建。

Authentication

身份验证

For Development / CLI

开发/CLI环境

Authenticate with the Membrane CLI for development and testing:

bash

npx @membranehq/cli login --tenant

Alternatively, install globally (

npm i -g @membranehq/cli@latest

) and use

membrane login --tenant

Always use

--tenant

to get a tenant-scoped token — this authenticates on behalf of a specific tenant (workspace + customer), so you don't need to pass

--workspaceKey

and

--tenantKey

on every subsequent command.

This opens a browser or prints an authorization URL. The user authenticates in Membrane, then selects a workspace and tenant.

Credentials are stored in

~/.membrane/credentials.json

在开发和测试环境中，使用Membrane CLI进行身份验证：

bash

npx @membranehq/cli login --tenant

或者全局安装（

npm i -g @membranehq/cli@latest

）后使用

membrane login --tenant

。

请始终使用

--tenant

参数获取租户范围的令牌——这代表特定租户（工作区+客户）进行身份验证，后续命令无需再传递

--workspaceKey

和

--tenantKey

。

此命令会打开浏览器或打印授权URL，用户在Membrane中完成身份验证后，选择工作区和租户即可。

凭据会存储在

~/.membrane/credentials.json

中。

Non-interactive Authentication

非交互式身份验证

If browser login is not available (remote/headless), the CLI prints an authorization URL. Ask the user to open it and enter the code they see:

bash

npx @membranehq/cli login complete <code>

若无法使用浏览器登录（远程/无头环境），CLI会打印授权URL，请让用户打开该URL并输入显示的验证码：

bash

npx @membranehq/cli login complete <code>

For Production (Backend Token Generation)

生产环境（后端令牌生成）

In production, your backend generates JWT tokens per customer per request:

javascript

import jwt from 'jsonwebtoken'

function generateMembraneToken(customerId, customerName) {
  return jwt.sign(
    {
      id: customerId,
      name: customerName,
    },
    process.env.MEMBRANE_WORKSPACE_SECRET,
    {
      issuer: process.env.MEMBRANE_WORKSPACE_KEY,
      expiresIn: '2h',
    },
  )
}

Create an endpoint on your backend (e.g.

/api/membrane-token

) that returns this token. The frontend SDK calls this to authenticate.

在生产环境中，你的后端需要为每个客户的每个请求生成JWT令牌：

javascript

import jwt from 'jsonwebtoken'

function generateMembraneToken(customerId, customerName) {
  return jwt.sign(
    {
      id: customerId,
      name: customerName,
    },
    process.env.MEMBRANE_WORKSPACE_SECRET,
    {
      issuer: process.env.MEMBRANE_WORKSPACE_KEY,
      expiresIn: '2h',
    },
  )
}

在你的后端创建一个端点（如

/api/membrane-token

）来返回此令牌，前端SDK会调用该端点进行身份验证。

Adding Integrations to Your App

为应用添加集成功能

There are three main ways to use Membrane in your app:

在应用中使用Membrane主要有三种方式：

Option A: JavaScript SDK (Frontend)

选项A：JavaScript SDK（前端）

bash

npm install @membranehq/sdk

javascript

import { MembraneClient } from '@membranehq/sdk'

const membrane = new MembraneClient({
  fetchToken: async () => {
    const response = await fetch('/api/membrane-token')
    const { token } = await response.json()
    return token
  },
})

// List available integrations
const integrations = await membrane.integrations.find()

// Open connection UI (popup)
await membrane.ui.connect({ integrationKey: 'hubspot' })

// List customer's connections
const connections = await membrane.connections.find()

// Reconnect a disconnected connection
await membrane.ui.connect({ connectionId: 'conn_123' })

// Delete a connection
await membrane.connection('conn_123').archive()

bash

npm install @membranehq/sdk

javascript

import { MembraneClient } from '@membranehq/sdk'

const membrane = new MembraneClient({
  fetchToken: async () => {
    const response = await fetch('/api/membrane-token')
    const { token } = await response.json()
    return token
  },
})

// 列出可用集成
const integrations = await membrane.integrations.find()

// 打开连接UI（弹窗）
await membrane.ui.connect({ integrationKey: 'hubspot' })

// 列出客户的连接
const connections = await membrane.connections.find()

// 重新连接已断开的连接
await membrane.ui.connect({ connectionId: 'conn_123' })

// 删除连接
await membrane.connection('conn_123').archive()

Option B: React SDK (Frontend)

选项B：React SDK（前端）

bash

npm install @membranehq/react

jsx

import { MembraneProvider, useIntegrations, useConnections, useMembrane } from '@membranehq/react'

function App() {
  return (
    <MembraneProvider
      fetchToken={async () => {
        const res = await fetch('/api/membrane-token')
        const { token } = await res.json()
        return token
      }}
    >
      <IntegrationsPage />
    </MembraneProvider>
  )
}

function IntegrationsPage() {
  const { items: integrations, loading } = useIntegrations()
  const { items: connections } = useConnections()
  const membrane = useMembrane()

  const handleConnect = (integrationKey) => {
    membrane.ui.connect({ integrationKey })
  }

  // ... render integrations list with connect buttons
}

bash

npm install @membranehq/react

jsx

import { MembraneProvider, useIntegrations, useConnections, useMembrane } from '@membranehq/react'

function App() {
  return (
    <MembraneProvider
      fetchToken={async () => {
        const res = await fetch('/api/membrane-token')
        const { token } = await res.json()
        return token
      }}
    >
      <IntegrationsPage />
    </MembraneProvider>
  )
}

function IntegrationsPage() {
  const { items: integrations, loading } = useIntegrations()
  const { items: connections } = useConnections()
  const membrane = useMembrane()

  const handleConnect = (integrationKey) => {
    membrane.ui.connect({ integrationKey })
  }

  // ... 渲染集成列表及连接按钮
}

Option C: REST API (Backend)

选项C：REST API（后端）

Use the Membrane API directly from your backend.

Base URL:

https://api.getmembrane.com

(or

https://api.integration.app

) Auth:

Authorization: Bearer <token>

bash

undefined

直接从你的后端调用Membrane API。

基础URL：

https://api.getmembrane.com

（或

https://api.integration.app

）身份验证：

Authorization: Bearer <token>

bash

undefined

List integrations

列出集成

GET /integrations

List connections

列出连接

GET /connections

Create connection request (returns auth URL)

创建连接请求（返回授权URL）

POST /connection-requests {"connectorId": "<id>"}

Check connection request status

检查连接请求状态

GET /connection-requests/<id>

List actions for a connection

列出连接的操作

GET /actions?connectionId=<id>

Run an action

执行操作

POST /actions/<id>/run?connectionId=<cid> {"input": {"channel": "#general", "text": "Hello!"}}

undefined

POST /actions/<id>/run?connectionId=<cid> {"input": {"channel": "#general", "text": "Hello!"}}

undefined

Connection UI

连接UI

Membrane provides a pre-built connection UI that handles OAuth flows and credential collection:

https://ui.integration.app/embed/integrations/{INTEGRATION_KEY}/connect?token={TOKEN}

Use in an iframe or redirect. Optional query params:

```
redirectUri
```
— redirect back after connection
```
allowMultipleConnections=1
```
— allow multiple connections per integration
```
name
```
— pre-set connection name

For reconnecting disconnected connections:

https://ui.integration.app/embed/connections/{CONNECTION_ID}/refresh?token={TOKEN}

Membrane提供预构建的连接UI，用于处理OAuth流程和凭据收集：

https://ui.integration.app/embed/integrations/{INTEGRATION_KEY}/connect?token={TOKEN}

可在iframe中嵌入或重定向到该页面，可选查询参数：

```
redirectUri
```
——连接完成后重定向的地址
```
allowMultipleConnections=1
```
——允许每个集成存在多个连接
```
name
```
——预设置连接名称

重新连接已断开的连接：

https://ui.integration.app/embed/connections/{CONNECTION_ID}/refresh?token={TOKEN}

Running Actions

执行操作

Actions are operations on connected apps. Find and run them:

操作是对已连接应用执行的操作，可按以下方式查找和执行：

Using CLI

使用CLI

bash

undefined

bash

undefined

Search actions by intent

通过意图搜索操作

npx @membranehq/cli action list --connectionId abc123 --intent "send a message" --limit 10 --json

Run an action

执行操作

npx @membranehq/cli action run <actionId> --connectionId abc123 --input '{"channel": "#general", "text": "Hello!"}' --json

undefined

npx @membranehq/cli action run <actionId> --connectionId abc123 --input '{"channel": "#general", "text": "Hello!"}' --json

undefined

Using API

使用API

bash

undefined

bash

undefined

Search actions

搜索操作

GET /actions?connectionId=abc123&intent=send+a+message&limit=10

Run action

执行操作

POST /actions/<actionId>/run?connectionId=abc123 {"input": {"channel": "#general", "text": "Hello!"}}


Each action has:

- `id` — unique identifier
- `name`, `description` — what it does
- `inputSchema` — JSON Schema of accepted parameters
- `outputSchema` — JSON Schema of the return value

The result is in the `output` field of the response.

POST /actions/<actionId>/run?connectionId=abc123 {"input": {"channel": "#general", "text": "Hello!"}}


每个操作包含：

- `id`——唯一标识符
- `name`、`description`——操作说明
- `inputSchema`——接受参数的JSON Schema
- `outputSchema`——返回值的JSON Schema

执行结果在响应的`output`字段中。

AI Agent Tools

AI Agent工具

Membrane actions can serve as tools for AI agents. Two approaches:

Membrane操作可作为AI Agent的工具，有两种实现方式：

Static Tools (known toolset)

静态工具（已知工具集）

Use when you know which tools the agent needs before the session starts.

List connections:
```
GET /connections
```
Get actions for connection:
```
GET /actions?connectionId=<id>
```

Map to your agent's tool format:

javascript

const tools = actions.items.map((action) => ({
  id: action.id,
  name: action.name,
  description: action.description,
  inputSchema: action.inputSchema,
}))

When agent calls a tool:

POST /actions/<id>/run?connectionId=<cid>

with

{"input": {...}}

当你在会话开始前就知道Agent需要哪些工具时使用：

列出连接：
```
GET /connections
```
获取连接的操作：
```
GET /actions?connectionId=<id>
```

映射到你的Agent工具格式：

javascript

const tools = actions.items.map((action) => ({
  id: action.id,
  name: action.name,
  description: action.description,
  inputSchema: action.inputSchema,
}))

当Agent调用工具时：

POST /actions/<id>/run?connectionId=<cid>

，携带

{"input": {...}}

Dynamic Tools (runtime discovery)

动态工具（运行时发现）

Use when tools depend on user intent or conversation context.

Search actions by natural language intent:

bash

GET /actions?connectionId=abc123&intent=send+a+message

This uses semantic search to find the best matching actions.

当工具依赖于用户意图或对话上下文时使用：

通过自然语言意图搜索操作：

bash

GET /actions?connectionId=abc123&intent=send+a+message

此方法使用语义搜索查找最匹配的操作。

MCP Server

MCP服务器

Membrane provides an official MCP server for AI agents:

https://mcp.integration.app/sse?token={TOKEN}&productKey={PRODUCT_KEY}

Works with Claude, Cursor, and any MCP-compatible agent.

Membrane为AI Agent提供官方MCP服务器：

https://mcp.integration.app/sse?token={TOKEN}&productKey={PRODUCT_KEY}

兼容Claude、Cursor及所有支持MCP的Agent。

Working with Membrane Agent

使用Membrane Agent

Membrane Agent is an AI agent that builds integration elements (connectors, actions, data collections, flows) for you. You should not build these yourself — delegate to Membrane Agent instead.

Membrane Agent是一款AI Agent，可为你构建集成元素（连接器、操作、数据集合、流程）。你不应自行构建这些元素——请委托给Membrane Agent。

When to Use Membrane Agent

何时使用Membrane Agent

A connector for an external app doesn't exist yet
An action you need isn't available
You need a data collection, flow, or other integration element
You need to customize how an integration works

所需外部应用的连接器不存在
所需操作不可用
需要数据集合、流程或其他集成元素
需要自定义集成的工作方式

Creating Agent Sessions

创建Agent会话

Use the CLI to create agent sessions:

bash

npx @membranehq/cli agent-session create --agent <agentName> --message "<description>" --json

Available agent types:

```
connection-building
```
— builds connectors for external apps
```
action-building
```
— builds actions for connected apps
```
membrane
```
— general-purpose Membrane agent (can build any element)

使用CLI创建Agent会话：

bash

npx @membranehq/cli agent-session create --agent <agentName> --message "<description>" --json

可用Agent类型：

```
connection-building
```
——为外部应用构建连接器
```
action-building
```
——为已连接应用构建操作
```
membrane
```
——通用Membrane Agent（可构建任意元素）

Agent Session Workflow

Agent会话工作流

Create a session with a clear description of what you need:

bash

npx @membranehq/cli agent-session create --agent action-building --message "Create an action to send a message in a Slack channel for connection abc123" --json

Poll until complete — the agent works asynchronously:
bash
```
npx @membranehq/cli agent-session get <sessionId> --wait --json
```
- ```
state: "busy"
```
  — still working, poll again
- ```
state: "idle"
```
  — done with current request
- ```
status: "completed"
```
  — session finished
- ```
summary
```
  — description of what was done (available when idle)

Send follow-ups if needed:

bash

npx @membranehq/cli agent-session send <sessionId> --message "Also add support for thread replies" --json

Abort if something goes wrong:

bash

npx @membranehq/cli agent-session abort <sessionId> --json

创建会话，清晰描述需求：

bash

npx @membranehq/cli agent-session create --agent action-building --message "Create an action to send a message in a Slack channel for connection abc123" --json

轮询直到完成——Agent以异步方式工作：
bash
```
npx @membranehq/cli agent-session get <sessionId> --wait --json
```
- ```
state: "busy"
```
  ——仍在工作，请再次轮询
- ```
state: "idle"
```
  ——当前请求已完成
- ```
status: "completed"
```
  ——会话已结束
- ```
summary
```
  ——已完成工作的描述（仅在idle状态下可用）

若需补充则发送后续消息：

bash

npx @membranehq/cli agent-session send <sessionId> --message "Also add support for thread replies" --json

若出现问题则中止会话：

bash

npx @membranehq/cli agent-session abort <sessionId> --json

What to Delegate vs. What to Build

应委托与应自行构建的内容

Delegate to Membrane Agent:

Connectors (authentication, API clients, connection testing)
Actions (API mappings, input/output schemas, implementation logic)
Data Collections (field schemas, CRUD operations, pagination)
Flows (multi-step automation, event handling, scheduling)
External Events (webhook subscriptions, event parsing)
Field Mappings (data transformation between apps)

Build yourself:

Backend token generation endpoint
Frontend UI for displaying integrations and connections
Agent tool mapping (converting Membrane actions to your LLM's tool format)
Business logic that uses Membrane actions/data
Custom UI components for your integration experience

委托给Membrane Agent的内容：

连接器（身份验证、API客户端、连接测试）
操作（API映射、输入/输出Schema、实现逻辑）
数据集合（字段Schema、CRUD操作、分页）
流程（多步自动化、事件处理、调度）
外部事件（Webhook订阅、事件解析）
字段映射（应用间数据转换）

需自行构建的内容：

后端令牌生成端点
用于显示集成和连接的前端UI
Agent工具映射（将Membrane操作转换为你的LLM工具格式）
使用Membrane操作/数据的业务逻辑
自定义集成体验的UI组件

Tips for Effective Agent Prompts

有效Agent提示技巧

When creating agent sessions, provide:

Connection ID — always include when building actions (
```
for connection abc123
```
)

App name and URL — when building connectors (

Build a connector for Notion (https://notion.so)

)

Specific operation — describe exactly what the action should do (
```
Create an action to list all tasks assigned to the current user
```
)
Input/output expectations — what parameters should be accepted and what should be returned

创建Agent会话时，请提供：

连接ID——构建操作时务必包含（如
```
for connection abc123
```
）
应用名称和URL——构建连接器时提供（如
```
Build a connector for Notion (https://notion.so)
```
）

具体操作——准确描述操作应实现的功能（如

Create an action to list all tasks assigned to the current user

）

输入/输出预期——应接受哪些参数以及应返回哪些内容

Building a Connector via Agent

通过Agent构建连接器

If no connector exists for an app:

bash

undefined

若应用的连接器不存在：

bash

undefined

Search first

先搜索

npx @membranehq/cli search notion --elementType connector --json

If not found, build one

若未找到则构建

npx @membranehq/cli agent-session create --agent connection-building --message "Build a connector for Notion (https://notion.so)" --json

Poll for completion

轮询直到完成

npx @membranehq/cli agent-session get <sessionId> --wait --json

After built, create a connection

构建完成后创建连接

npx @membranehq/cli connect --connectorId <connectorId>

undefined

npx @membranehq/cli connect --connectorId <connectorId>

undefined

Building an Action via Agent

通过Agent构建操作

If the action you need doesn't exist:

bash

undefined

若所需操作不存在：

bash

undefined

Search first

先搜索

npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

If not found, build one

若未找到则构建

npx @membranehq/cli agent-session create --agent action-building --message "Create an action to create a task with title, description, and assignee for connection abc123" --json

Poll for completion

轮询直到完成

npx @membranehq/cli agent-session get <sessionId> --wait --json

Search again to get the action ID

再次搜索获取操作ID

npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

undefined

npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

undefined

Troubleshooting

故障排除

Connection Issues

连接问题

Check connection status:

bash

npx @membranehq/cli connection get <connectionId> --json

Key fields:

```
disconnected: true
```
— credentials expired or revoked, needs reconnection
```
error
```
— details about what went wrong

Reconnect:

bash

npx @membranehq/cli connect --connectionId <connectionId>

检查连接状态：

bash

npx @membranehq/cli connection get <connectionId> --json

关键字段：

```
disconnected: true
```
——凭据过期或被撤销，需要重新连接
```
error
```
——问题详情

重新连接：

bash

npx @membranehq/cli connect --connectionId <connectionId>

Action Errors

操作错误

When an action fails, the response includes error details. Common issues:

Missing required input — check
```
inputSchema
```
for required fields
Connection disconnected — reconnect before retrying
Rate limiting — the external app is rate-limiting requests, retry after delay
Permission denied — the connection's OAuth scope doesn't cover this operation

操作失败时，响应会包含错误详情，常见问题：

缺少必填输入——检查
```
inputSchema
```
中的必填字段
连接已断开——重新连接后重试
速率限制——外部应用限制请求频率，延迟后重试
权限不足——连接的OAuth权限范围不包含此操作

Finding the Right Action

查找正确的操作

action list --intent

doesn't return what you need:

Try different phrasings of your intent

List all actions without intent filter:

npx @membranehq/cli action list --connectionId abc123 --json

If the action doesn't exist, build it via Membrane Agent (see above)

若

action list --intent

未返回所需结果：

尝试不同的意图表述

不使用意图过滤器列出所有操作：

npx @membranehq/cli action list --connectionId abc123 --json

若操作不存在则通过Membrane Agent构建（见上文）

CLI Reference

CLI参考

All commands support

--json

for structured JSON output. Add

--workspaceKey <key>

and

--tenantKey <key>

to override defaults.

所有命令均支持

--json

参数以获取结构化JSON输出，可添加

--workspaceKey <key>

和

--tenantKey <key>

来覆盖默认设置。

connection

bash

npx @membranehq/cli connection list [--json]                # List all connections
npx @membranehq/cli connection get <id> [--json]           # Get a connection by ID

bash

npx @membranehq/cli connection list [--json]                # 列出所有连接
npx @membranehq/cli connection get <id> [--json]           # 通过ID获取连接

connect (interactive)

connect（交互式）

bash

npx @membranehq/cli connect --connectorId <id>                    # Create connection via browser OAuth
npx @membranehq/cli connect --connectionId <id>                   # Reconnect existing connection

Opens a browser for authentication. Use

--non-interactive

to print the URL instead.

bash

npx @membranehq/cli connect --connectorId <id>                    # 通过浏览器OAuth创建连接
npx @membranehq/cli connect --connectionId <id>                   # 重新连接现有连接

打开浏览器进行身份验证，使用

--non-interactive

参数可打印URL而非打开浏览器。

connection-request

bash

npx @membranehq/cli connection-request create [options] [--json]   # Create connection request
npx @membranehq/cli connection-request get <requestId> [--json]    # Check request status

Options:

--connectorId <id>

--integrationId <id>

--integrationKey <key>

--connectionId <id>

(reconnect),

--name <name>

Status values:

pending

success

error

cancelled

bash

npx @membranehq/cli connection-request create [options] [--json]   # 创建连接请求
npx @membranehq/cli connection-request get <requestId> [--json]    # 检查请求状态

选项：

--connectorId <id>

--integrationId <id>

--integrationKey <key>

--connectionId <id>

（重新连接）,

--name <name>

状态值：

pending

success

error

cancelled

action

bash

npx @membranehq/cli action list [--connectionId <id>] [--intent <text>] [--limit <n>] [--json]   # List/search actions
npx @membranehq/cli action run <actionId> --connectionId <id> [--input <json>] [--json]           # Run an action

bash

npx @membranehq/cli action list [--connectionId <id>] [--intent <text>] [--limit <n>] [--json]   # 列出/搜索操作
npx @membranehq/cli action run <actionId> --connectionId <id> [--input <json>] [--json]           # 执行操作

search

bash

npx @membranehq/cli search <query> [--elementType <type>] [--limit <n>] [--json]   # Search connectors, integrations, etc.

bash

npx @membranehq/cli search <query> [--elementType <type>] [--limit <n>] [--json]   # 搜索连接器、集成等

agent-session

bash

npx @membranehq/cli agent-session create --agent <agentName> --message <text> [--json]   # Create session
npx @membranehq/cli agent-session list [--json]                                          # List sessions
npx @membranehq/cli agent-session get <id> [--wait] [--timeout <seconds>] [--json]       # Get status
npx @membranehq/cli agent-session send <id> --message <text> [--json]                    # Send follow-up
npx @membranehq/cli agent-session abort <id> [--json]                                    # Abort session
npx @membranehq/cli agent-session messages <id> [--json]                                 # Get messages

bash

npx @membranehq/cli agent-session create --agent <agentName> --message <text> [--json]   # 创建会话
npx @membranehq/cli agent-session list [--json]                                          # 列出会话
npx @membranehq/cli agent-session get <id> [--wait] [--timeout <seconds>] [--json]       # 获取状态
npx @membranehq/cli agent-session send <id> --message <text> [--json]                    # 发送后续消息
npx @membranehq/cli agent-session abort <id> [--json]                                    # 中止会话
npx @membranehq/cli agent-session messages <id> [--json]                                 # 获取消息

Fallback: Raw API

备选方案：直接调用API

If the CLI is not available, make direct API requests.

Base URL:

https://api.getmembrane.com

Auth header:

Authorization: Bearer $MEMBRANE_TOKEN

CLI Command	API Equivalent
`connection list --json`	`GET /connections`
`connection get <id> --json`	`GET /connections/:id`
`search <q> --json`	`GET /search?q=<q>`
`connection-request create --connectorId <id> --json`	`POST /connection-requests` with `{"connectorId": "<id>"}`
`connection-request get <id> --json`	`GET /connection-requests/:id`
`action list --connectionId <id> --intent <text> --json`	`GET /actions?connectionId=<id>&intent=<text>`
`action run <id> --connectionId <cid> --input <json> --json`	`POST /actions/:id/run?connectionId=<cid>` with `{"input": <json>}`
`agent-session create --message <text> --json`	`POST /agent/sessions` with `{"prompt": "<text>"}`
`agent-session get <id> --wait --json`	`GET /agent/sessions/:id?wait=true`
`agent-session send <id> --message <text> --json`	`POST /agent/sessions/:id/message` with `{"input": "<text>"}`
`agent-session abort <id> --json`	`POST /agent/sessions/:id/interrupt`

若无法使用CLI，可直接发送API请求。

基础URL：

https://api.getmembrane.com

身份验证头：

Authorization: Bearer $MEMBRANE_TOKEN

CLI命令	API等效请求
`connection list --json`	`GET /connections`
`connection get <id> --json`	`GET /connections/:id`
`search <q> --json`	`GET /search?q=<q>`
`connection-request create --connectorId <id> --json`	`POST /connection-requests` 携带 `{"connectorId": "<id>"}`
`connection-request get <id> --json`	`GET /connection-requests/:id`
`action list --connectionId <id> --intent <text> --json`	`GET /actions?connectionId=<id>&intent=<text>`
`action run <id> --connectionId <cid> --input <json> --json`	`POST /actions/:id/run?connectionId=<cid>` 携带 `{"input": <json>}`
`agent-session create --message <text> --json`	`POST /agent/sessions` 携带 `{"prompt": "<text>"}`
`agent-session get <id> --wait --json`	`GET /agent/sessions/:id?wait=true`
`agent-session send <id> --message <text> --json`	`POST /agent/sessions/:id/message` 携带 `{"input": "<text>"}`
`agent-session abort <id> --json`	`POST /agent/sessions/:id/interrupt`

External Endpoints

外部端点

All requests go to the Membrane API. No other external services are contacted directly by this skill.

Endpoint	Data Sent
`https://api.getmembrane.com/*`	Auth credentials, connection parameters, action inputs, agent prompts

所有请求均发送至Membrane API，本技能不会直接调用其他外部服务。

端点	发送的数据
`https://api.getmembrane.com/*`	身份验证凭据、连接参数、操作输入、Agent提示

Security & Privacy

安全与隐私

All data is sent to the Membrane API over HTTPS.
CLI credentials are stored locally in
```
~/.membrane/
```
with restricted file permissions.
Connection authentication (OAuth, API keys) is handled by Membrane — credentials for external apps are stored by the Membrane service, not locally.
Action inputs and outputs pass through the Membrane API to the connected external app.
Never expose your Workspace Secret to the frontend. Token generation must happen on your backend.

By using this skill, data is sent to Membrane. Only install if you trust Membrane with access to your connected apps.

所有数据均通过HTTPS发送至Membrane API。
CLI凭据存储在本地
```
~/.membrane/
```
目录中，文件权限受限制。
连接身份验证（OAuth、API密钥）由Membrane处理——外部应用的凭据由Membrane服务存储，而非本地存储。
操作的输入和输出会通过Membrane API传递至已连接的外部应用。
绝不能将你的工作区密钥暴露给前端，令牌生成必须在后端完成。

使用本技能即表示数据会发送至Membrane，请仅在你信任Membrane可访问已连接应用的情况下使用。