Integration App MCP Server

Membrane MCP Server

Membrane MCP Server — это сервер Model Context Protocol (MCP), который предоставляет действия для подключенных интеграций в Membrane в виде инструментов.

Вот наш официальный пример AI-агента, который показывает, как использовать этот MCP-сервер в вашем приложении.

📋 Предварительные требования

• Node.js (v18 или выше)
• Учетная запись Membrane

⚙️ Установка

git clone https://github.com/membranehq/mcp-server.git
cd mcp-server
npm install
npm run build

🛠️ Локальная разработка

Чтобы запустить сервер разработки локально, выполните:

npm run dev

Сервер будет доступен по адресу http://localhost:3000 ⚡️

🧪 Запуск тестов

# Run the server in test mode
npm run start:test

# then run tests
npm test

🚀 Развертывание

Разверните собственный экземпляр этого MCP-сервера в любом облачном хостинге на ваш выбор.

🐳 Docker

Проект включает Dockerfile для удобного развертывания в контейнере.

docker build -t membrane-mcp-server .
docker run -p 3000:3000 membrane-mcp-server

🔗 Подключение к MCP-серверу

Этот MCP-сервер поддерживает два транспорта:

Транспорт	Конечная точка	Статус
SSE (Server‑Sent Events)	/sse	🔴 Устарел — объявлен устаревшим с 5 ноября 2024 года в спецификации MCP
HTTP (Streamable HTTP)	/mcp	🟢 Рекомендуется — заменяет SSE и поддерживает двунаправленную потоковую передачу

🔐 Аутентификация

Предоставьте токен доступа Membrane через параметр запроса или заголовок Authorization:

?token=ACCESS_TOKEN
Authorization: Bearer ACCESS_TOKEN

SSE (Устаревший)

await client.connect(
  new SSEClientTransport(
    new URL(
      `https://<HOSTED_MCP_SERVER_URL>/sse`
    )
    {
      requestInit: {
        headers: {
          Authorization: `Bearer ${ACCESS_TOKEN}`,
        },
      },
    }
  )
);

Streamable HTTP (Рекомендуемый)

await client.connect(
  new StreamableHTTPClientTransport(
    new URL(`https://<HOSTED_MCP_SERVER_URL>/mcp`)
    {
      requestInit: {
        headers: {
          Authorization: `Bearer ${ACCESS_TOKEN}`,
        },
      },
    }
  )
);

⚡ Статический и динамический режимы

По умолчанию MCP-сервер работает в статическом режиме, что означает, что он возвращает все доступные инструменты (действия) для всех подключенных интеграций.

В динамическом режиме (?mode=dynamic) сервер вернет только один инструмент: enable-tools. Вы можете использовать этот инструмент, чтобы выборочно включить только те инструменты, которые действительно нужны для данной сессии.

В динамическом режиме ваша реализация должна определить, какие инструменты наиболее релевантны запросу пользователя. После того как вы их определили, предложите LLM вызвать инструмент enable-tools с соответствующим списком.

Хотите увидеть, как это работает на практике? Ознакомьтесь с нашим примером AI-агента.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({
  name: 'example-membrane-mcp-client',
  version: '1.0.0',
});

const transport = new StreamableHTTPClientTransport(
  new URL(`https://<HOSTED_MCP_SERVER_URL>/mcp?mode=dynamic`),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${ACCESS_TOKEN}`,
      },
    },
  }
);

await client.connect(transport);

await client.callTool({
  name: 'enable-tools',
  arguments: {
    tools: ['gmail-send-email', 'gmail-read-email'],
  },
});

🔧 Получение инструментов для конкретных интеграций

В статическом режиме MCP-сервер извлекает инструменты из всех активных подключений, связанных с предоставленным токеном.

Вы можете выбрать получение инструментов только для конкретной интеграции, передав параметр запроса apps: /mcp?apps=google-calendar,google-docs

💬 Управление сессиями чата (Экспериментальная функция)

MCP-сервер (только транспорт streamable-http) поддерживает постоянные сессии чата. Включите заголовок x-chat-id в ваши запросы, чтобы автоматически отслеживать сессии для этого конкретного чата. Это экспериментальная функция, которую мы предоставляем в дополнение к стандартным сессиям MCP.

Начало новой сессии чата:

POST /mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
x-chat-id: my-awesome-chat-123

Получение ваших сессий чата:

GET /mcp/sessions
Authorization: Bearer YOUR_ACCESS_TOKEN

Ответ:

{
  "my-awesome-chat-123": "session-uuid-1",
  "another-chat-456": "session-uuid-2"
}

Эта функция позволяет использовать одну и ту же сессию для разговора. Ознакомьтесь с нашим примером AI-агента, чтобы увидеть, как это работает на практике.

Настройка других MCP-клиентов

📝 Cursor

Чтобы использовать этот сервер с Cursor, обновите файл ~/.cursor/mcp.json:

{
  "mcpServers": {
    "membrane": {
      "url": "https://<HOSTED_MCP_SERVER_URL>/sse?token={ACCESS_TOKEN}"
    }
  }
}

Перезапустите Cursor, чтобы изменения вступили в силу.

🤖 Claude Desktop

Чтобы использовать этот сервер с Claude, обновите файл конфигурации (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "membrane": {
      "url": "https://<HOSTED_MCP_SERVER_URL>/sse?token={ACCESS_TOKEN}"
    }
  }
}

🔧 Устранение неполадок

• Убедитесь, что ваш токен доступа действителен и вы генерируете его в соответствии с этими инструкциями
• Проверьте журналы MCP-сервера на наличие ошибок или проблем во время запуска или попыток подключения.
• Используйте MCP Inspector для тестирования и отладки