build-product-integrations

アプリの統合

Membrane を通じて外部サービスと連携するアプリを構築します。Membrane CLI を使用します。

サードパーティーとの連携を製品に追加する必要がある場合に、このスキルを使用します。顧客を外部アプリに接続したり、顧客に代わってアクションを実行したり、データを同期したり、AI エージェント用のツールを提供したりできます。

Membrane の仕組み

Membrane は統合エンジンです。アプリに必要なもの（外部アプリ、操作、データ）を定義すると、Membrane が認証、API 呼び出し、データ変換を処理します。

中核となる概念

ワークスペース — Membrane 上のプロジェクトです。製品のすべての統合、コネクター、設定が含まれます。

顧客 — 製品のユーザーまたは組織です。顧客ごとに独自の接続と統合状態が用意されます。選択した一意の ID（ユーザー ID／組織 ID など）で識別されます。

コネクター — 外部アプリ（Slack、HubSpot など）用の構築済みアダプターです。認証（OAuth、API キー）、API クライアントの設定、接続テストを処理します。Membrane には数千ものアプリ向けのコネクターがあります。存在しない場合は、Membrane Agent が構築できます。

統合 — 製品と外部アプリとの関係です。ワークスペースで定義され、特定のアプリ向けのコネクター、アクション、データコレクション、フローをまとめます。

接続 — 顧客と外部アプリ間の認証済みリンクです。顧客が OAuth／認証フローを完了すると作成されます。Membrane が管理する認証情報が含まれます。

アクション — 接続済みアプリに対する単一の操作です（「メッセージを送信」「タスクを作成」「連絡先を一覧表示」など）。型付きの inputSchema と outputSchema を持ちます。API 経由で実行するか、AI エージェント用のツールとして使用できます。

データコレクション — データベーステーブルのように、外部アプリのデータを操作するための一貫した API です。一覧表示、検索、作成、更新、削除の操作に対応しています。

フロー — イベント、スケジュール、API 呼び出しによってトリガーされる、複数ステップの非同期ロジックです。トリガー、関数、制御ノードで構成されます。

要素のレイヤー

Membrane の要素は、次の 3 つのレイヤーに存在します。

1. ユニバーサル — 複数の外部アプリで動作します（特定の統合に限定されません）。例：任意のタスク管理アプリで動作する「タスクを作成」アクション。
2. 統合 — 1 つの外部アプリに固有です（integrationId を持ちます）。例：「Jira の課題を作成」アクション。
3. 接続 — 顧客の接続に固有です（connectionId を持ちます）。顧客ごとに統合レベルの要素をカスタマイズできます。

統合レベルの要素には、統合ごとの実装が必要です。接続レベルの要素では、統合レベルのデフォルトを上書き／カスタマイズできます。

認証アーキテクチャ

Membrane は API アクセスに JWT トークンを使用します。

• ワークスペースキー — ワークスペースを識別します（JWT の iss クレームとして設定されます）。
• ワークスペースシークレット — トークンの署名に使用します（フロントエンドには絶対に公開しないでください）。
• 顧客トークン — ワークスペースキーと顧客 ID を含む JWT です。バックエンドで生成し、フロントエンドの SDK と API 呼び出しで使用します。

外部アプリの認証情報（OAuth トークン、API キー）は Membrane が管理するため、アプリが直接扱うことはありません。

標準的なワークフロー：検索 → 使用 → 委任

Membrane を使用する際は、必ず次のパターンに従ってください。

1. 必要なものを検索する — インテント検索を使って、アクション、コネクター、統合を見つけます。
2. 存在する場合は使用する — アクションを実行したり、コネクターで接続したりします。
3. 存在しない場合は Membrane Agent に委任する — 不足している要素を構築するためのエージェントセッションを作成します。

例：ユーザーが Slack のチャンネル一覧を表示したい場合

# Step 1: Search for a "list channels" action
npx @membranehq/cli action list --connectionId <slack-conn-id> --intent "list channels" --limit 5 --json

# Step 2: If found, run it
npx @membranehq/cli action run <actionId> --connectionId <slack-conn-id> --json

# Step 3: If NOT found, delegate to 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

例：ユーザーが新しいアプリ（Notion など）を追加したい場合

# Step 1: Search for existing Notion connector
npx @membranehq/cli search notion --elementType connector --json

# Step 2: If found, create a connection
npx @membranehq/cli connect --connectorId <connectorId>

# Step 3: If NOT found, delegate to 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

このパターンは Membrane のあらゆる要素に適用されます。 要素（アクション、コネクター、データコレクション、フロー）が存在しない場合は、必ず Membrane Agent に構築を委任してください。自分で構築しようとしてはいけません。

認証

開発／CLI 向け

開発およびテスト用に、Membrane CLI で認証します。

npx @membranehq/cli login --tenant

または、グローバルにインストール（npm i -g @membranehq/cli@latest）して、membrane login --tenant を使用します。

テナントスコープのトークンを取得するには、必ず --tenant を使用してください。これにより、特定のテナント（ワークスペース＋顧客）に代わって認証されるため、以降の各コマンドで --workspaceKey と --tenantKey を渡す必要がありません。

ブラウザーが開くか、認証 URL が表示されます。ユーザーは Membrane で認証し、その後ワークスペースとテナントを選択します。

認証情報は ~/.membrane/credentials.json に保存されます。

非対話型認証

ブラウザーログインを利用できない場合（リモート／ヘッドレス環境）、CLI は認証 URL を表示します。ユーザーに URL を開いてもらい、表示されたコードを入力してもらってください。

npx @membranehq/cli login complete <code>

本番環境向け（バックエンドでのトークン生成）

本番環境では、バックエンドがリクエストごと、顧客ごとに JWT トークンを生成します。

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 は、このエンドポイントを呼び出して認証します。

アプリへのインテグレーションの追加

アプリで Membrane を使用する方法は、主に 3 つあります。

オプション A：JavaScript SDK（フロントエンド）

npm install @membranehq/sdk

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()

オプション B：React SDK（フロントエンド）

npm install @membranehq/react

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
}

オプション C：REST API（バックエンド）

バックエンドから Membrane API を直接使用します。

ベース URL：https://api.getmembrane.com（または https://api.integration.app） 認証：Authorization: Bearer <token>

# List integrations
GET /integrations

# List connections
GET /connections

# Create connection request (returns auth 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!"}}

接続 UI

Membrane は、OAuth フローと認証情報の収集を処理する、すぐに使える接続 UI を提供します。

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}

アクションの実行

アクションは、接続済みアプリに対する操作です。アクションを検索して実行します。

CLI の使用

# 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

API の使用

# 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!"}}

各アクションには、次の情報があります。

• id — 一意の識別子
• name、description — アクションの内容
• inputSchema — 受け付けるパラメーターの JSON Schema
• outputSchema — 戻り値の JSON Schema

結果はレスポンスの output フィールドに含まれます。

AI エージェント向けツール

Membrane のアクションは、AI エージェント向けのツールとして使用できます。方法は 2 つあります。

静的ツール（既知のツールセット）

セッション開始前に、エージェントが必要とするツールがわかっている場合に使用します。

1. 接続を一覧表示する：GET /connections
2. 接続に対応するアクションを取得する：GET /actions?connectionId=<id>
3. エージェントのツール形式にマッピングする：

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

4. エージェントがツールを呼び出したら、{"input": {...}} を指定して POST /actions/<id>/run?connectionId=<cid> を実行する

動的ツール（実行時の検出）

ツールがユーザーの意図や会話のコンテキストに応じて変わる場合に使用します。

自然言語の意図からアクションを検索します。

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

これにより、セマンティック検索を使用して、最も一致するアクションを見つけます。

MCP サーバー

Membrane は、AI エージェント向けの公式 MCP サーバーを提供しています。

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

Claude、Cursor、および MCP 互換のあらゆるエージェントで動作します。

Membrane Agent の利用

Membrane Agent は、インテグレーション要素（コネクター、アクション、データコレクション、フロー）を構築する AI エージェントです。これらを自分で構築せず、代わりに Membrane Agent に委任してください。

Membrane Agent を使用するタイミング

• 外部アプリ用のコネクターがまだ存在しない場合
• 必要なアクションが利用できない場合
• データコレクション、フロー、その他のインテグレーション要素が必要な場合
• インテグレーションの動作をカスタマイズする必要がある場合

エージェントセッションの作成

CLI を使用してエージェントセッションを作成します。

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

利用可能なエージェントの種類：

• connection-building — 外部アプリ用のコネクターを構築します
• action-building — 接続済みアプリ用のアクションを構築します
• membrane — 汎用の Membrane エージェント（あらゆる要素を構築できます）

エージェントセッションのワークフロー

1. セッションを作成し、必要な作業を明確に説明します：

   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
   

2. 完了するまでポーリングします — エージェントは非同期で動作します：

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

   • state: "busy" — 作業中です。再度ポーリングしてください
   • state: "idle" — 現在のリクエストが完了しました
   • status: "completed" — セッションが終了しました
   • summary — 実行した作業の説明（アイドル状態のときに利用可能）

3. 必要に応じて追加のリクエストを送信します：

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

4. 問題が発生した場合は中止します：

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

委任する作業と自分で構築する作業

Membrane Agent に委任する作業：

• コネクター（認証、API クライアント、接続テスト）
• アクション（API マッピング、入出力スキーマ、実装ロジック）
• データコレクション（フィールドスキーマ、CRUD 操作、ページネーション）
• フロー（複数ステップの自動化、イベント処理、スケジューリング）
• 外部イベント（Webhook サブスクリプション、イベント解析）
• フィールドマッピング（アプリ間のデータ変換）

自分で構築する作業：

• バックエンドのトークン生成エンドポイント
• インテグレーションと接続を表示するフロントエンド UI
• エージェントのツールマッピング（Membrane アクションを LLM のツール形式に変換）
• Membrane アクション／データを使用するビジネスロジック
• インテグレーション体験向けのカスタム UI コンポーネント

効果的なエージェントプロンプトのヒント

エージェントセッションを作成するときは、次の情報を指定してください：

• 接続 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）
• 入出力の要件 — 受け付けるパラメーターと返す値を指定します

エージェントを使ったコネクターの構築

アプリ用のコネクターが存在しない場合：

# 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>

エージェントを使ったアクションの構築

必要なアクションが存在しない場合：

# 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
npx @membranehq/cli action list --connectionId abc123 --intent "create a task" --limit 10 --json

トラブルシューティング

接続の問題

接続ステータスを確認します：

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

主なフィールド：

• disconnected: true — 認証情報の有効期限が切れたか、取り消されています。再接続が必要です
• error — 問題の詳細

再接続します：

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

アクションのエラー

アクションが失敗すると、応答にエラーの詳細が含まれます。よくある問題：

• 必須入力の不足 — 必須フィールドを確認するには inputSchema を確認してください
• 接続の切断 — 再試行する前に再接続してください
• レート制限 — 外部アプリがリクエストを制限しています。時間をおいてから再試行してください
• 権限の拒否 — 接続の OAuth スコープがこの操作に対応していません

適切なアクションを見つける

action list --intent で必要なアクションが返されない場合：

1. 意図を異なる表現で試します
2. 意図フィルターを指定せずにすべてのアクションを一覧表示します：npx @membranehq/cli action list --connectionId abc123 --json
3. アクションが存在しない場合は、Membrane Agent を使って構築します（上記を参照）

CLI リファレンス

すべてのコマンドで、構造化された JSON 出力を得るために --json を使用できます。デフォルトを上書きするには、--workspaceKey <key> と --tenantKey <key> を追加します。

connection

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

connect（対話型）

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

認証のためにブラウザーを開きます。代わりに URL を出力するには、--non-interactive を使用します。

connection-request

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

オプション：--connectorId <id>、--integrationId <id>、--integrationKey <key>、--connectionId <id>（再接続）、--name <name>

ステータスの値：pending、success、error、cancelled

action

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

search

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

agent-session

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

フォールバック：Raw API

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

外部エンドポイント

すべてのリクエストは Membrane API に送信されます。このスキルから他の外部サービスに直接接続することはありません。

エンドポイント	送信されるデータ
https://api.getmembrane.com/*	認証情報、接続パラメーター、アクションの入力、エージェントのプロンプト

セキュリティとプライバシー

• すべてのデータは HTTPS 経由で Membrane API に送信されます。
• CLI の認証情報は、アクセス権限が制限された状態でローカルの ~/.membrane/ に保存されます。
• 接続の認証（OAuth、API キー）は Membrane が処理します。外部アプリの認証情報はローカルではなく、Membrane サービスによって保存されます。
• アクションの入力と出力は、Membrane API を経由して接続先の外部アプリに渡されます。
• Workspace Secret をフロントエンドに公開しないでください。トークンの生成はバックエンドで行う必要があります。

このスキルを使用すると、データが Membrane に送信されます。接続済みアプリへのアクセスを Membrane に許可しても問題ない場合にのみインストールしてください。