Integration App

Membrane MCP 서버

Membrane MCP 서버는 모델 컨텍스트 프로토콜 (MCP) 서버로, 연결된 통합에 대한 액션을 도구로서 제공합니다.

다음은 이 MCP 서버를 애플리케이션에서 사용하는 방법을 보여주는 공식 AI 에이전트 예제입니다.

📋 사전 준비 사항

• 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 (서버 전송 이벤트)	/sse	🔴 지원 중단 — 2024년 11월 5일 MCP 사양에서 지원 중단됨
HTTP (스트리밍 가능 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}`,
        },
      },
    }
  )
);

스트리밍 가능 HTTP (권장)

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

⚡ 정적 모드 vs 동적 모드

기본적으로 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 서버(스트리밍 가능 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와 함께 사용하려면 구성 파일(설정 > 개발자 > 구성 편집)을 업데이트하세요:

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

🔧 문제 해결

• 액세스 토큰이 유효하고 이 지침에 따라 생성되었는지 확인하세요.
• 시작 또는 연결 시도 중 오류나 문제가 있는지 MCP 서버 로그를 확인하세요.
• 테스트 및 디버깅을 위해 MCP 인스펙터를 사용하세요.