Integration App MCP Server

Membrane MCP Server

O Membrane MCP Server é um servidor Model Context Protocol (MCP), que fornece ações para integrações conectadas no Membrane como ferramentas.

Aqui está nosso Exemplo de Agente de IA oficial que mostra como usar este servidor MCP na sua aplicação.

📋 Pré-requisitos

• Node.js (v18 ou superior)
• Uma conta no Membrane

⚙️ Instalação

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

🛠️ Desenvolvimento Local

Para executar o servidor de desenvolvimento localmente, inicie-o com:

npm run dev

O servidor estará ativo em http://localhost:3000 ⚡️

🧪 Executando testes

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

# then run tests
npm test

🚀 Implantação

Implante sua própria instância deste servidor MCP em qualquer serviço de hospedagem em nuvem de sua escolha.

🐳 Docker

O projeto inclui um Dockerfile para facilitar a implantação em contêineres.

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

🔗 Conectando-se ao servidor MCP

Este servidor MCP suporta dois transportes:

Transporte	Endpoint	Status
SSE (Server‑Sent Events)	/sse	🔴 Obsoleto — obsoleto desde 5 de novembro de 2024 na especificação MCP
HTTP (Streamable HTTP)	/mcp	🟢 Recomendado — substitui SSE e suporta streaming bidirecional

🔐 Autenticação

Forneça um token de acesso do Membrane via query ou cabeçalho Authorization:

?token=ACCESS_TOKEN
Authorization: Bearer ACCESS_TOKEN

SSE (Obsoleto)

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

Streamable HTTP (Recomendado)

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

⚡ Modo Estático vs Dinâmico

Por padrão, o servidor MCP é executado em modo estático, o que significa que ele retorna todas as ferramentas disponíveis (ações) para todas as integrações conectadas.

Com o modo dinâmico (?mode=dynamic), o servidor retornará apenas uma ferramenta: enable-tools. Você pode usar essa ferramenta para habilitar seletivamente as ferramentas que realmente precisa para aquela sessão.

No modo dinâmico, sua implementação deve descobrir quais ferramentas são mais relevantes para a consulta do usuário. Depois de identificá-las, solicite ao LLM que chame a ferramenta enable-tools com a lista apropriada.

Quer ver como isso funciona na prática? Confira nosso Exemplo de Agente de IA.

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'],
  },
});

🔧 Obtendo ferramentas para integrações específicas

No modo estático, o servidor MCP busca ferramentas de todas as conexões ativas associadas ao token fornecido.

Você pode optar por buscar ferramentas apenas para uma integração específica passando o parâmetro de consulta apps: /mcp?apps=google-calendar,google-docs

💬 Gerenciamento de Sessão de Chat (Experimental)

O servidor MCP (apenas transporte streamable-http) suporta sessões de chat persistentes. Inclua um cabeçalho x-chat-id em suas requisições para rastrear automaticamente as sessões daquele chat específico. Este é um recurso experimental que fornecemos além das sessões MCP padrão.

Iniciando uma nova sessão de chat:

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

Recuperando suas sessões de chat:

GET /mcp/sessions
Authorization: Bearer YOUR_ACCESS_TOKEN

Resposta:

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

Este recurso permite que você use a mesma sessão para uma conversa. Confira nosso Exemplo de Agente de IA para ver como isso funciona na prática.

Configurando outros clientes MCP

📝 Cursor

Para usar este servidor com o Cursor, atualize o arquivo ~/.cursor/mcp.json:

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

Reinicie o Cursor para que as alterações tenham efeito.

🤖 Claude Desktop

Para usar este servidor com o Claude, atualize o arquivo de configuração (Configurações > Desenvolvedor > Editar Config):

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

🔧 Solução de Problemas

• Certifique-se de que seu token de acesso é válido e que você o está gerando de acordo com estas instruções
• Verifique os logs do servidor MCP para quaisquer erros ou problemas durante a inicialização ou tentativas de conexão.
• Use o MCP Inspector para testes e depuração