MCP Server

What is MCP Server about?

MCP Server exposes the tools (actions) of every integration linked to an Integration.app account through the Model Context Protocol transports. Clients can retrieve the full tool catalog or dynamically enable a subset, then invoke those tools during a conversation.

How to use MCP Server?

1. Clone and build

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

2. Run locally

   npm run dev
   # server listens on http://localhost:3000
   

3. Connect from a client – choose the recommended Streamable HTTP transport:

   import { Client } from '@modelcontextprotocol/sdk/client/index.js';
   import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
   
   const client = new Client({ name: 'my-client', version: '1.0.0' });
   const transport = new StreamableHTTPClientTransport(
     new URL('https://<HOSTED_MCP_SERVER_URL>/mcp'),
     { requestInit: { headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } } }
   );
   await client.connect(transport);
   

4. Fetch tools – static mode (/mcp) returns all tools; dynamic mode (/mcp?mode=dynamic) returns only enable-tools for selective activation.
5. Optional chat session – include x-chat-id header to keep a persistent session (experimental).

Key features

• Two transports: deprecated SSE (/sse) and recommended Streamable HTTP (/mcp).
• Static vs. dynamic mode for full‑catalog or on‑demand tool selection.
• Selective integration filtering via apps query parameter.
• Experimental persistent chat sessions with x-chat-id header.
• Docker support for containerised deployment.
• Easy configuration for popular MCP clients such as Cursor and Claude Desktop.

Use cases

• Powering AI agents that need to send emails, read calendars, or interact with any Integration.app tool.
• Building custom assistants that expose only a subset of tools relevant to a user request.
• Running a self‑hosted MCP endpoint for internal enterprise integrations.
• Extending existing AI workflows (e.g., Claude, Cursor) with organization‑specific actions.

FAQ

Q: Which transport should I use?

• A: Use the Streamable HTTP transport (/mcp). SSE is deprecated as of Nov 2024.

Q: How do I limit the tools returned?

• A: Pass ?mode=dynamic to get only the enable-tools tool, then call it with the list of desired tools. You can also filter by integration with ?apps=google-calendar,google-docs.

Q: Do I need to set up a database?

• A: No external database is required; the server reads active connections from Integration.app using the provided access token.

Q: Can I run the server in production?

• A: Yes. Build the Docker image (docker build -t integration-app-mcp-server .) and run it (docker run -p 3000:3000 integration-app-mcp-server).

Q: How are chat sessions handled?

• A: Include an x-chat-id header on each request. The server will map it to an internal session UUID, allowing stateful conversations across calls.

Integration App MCP Server

The Integration App MCP Server is a Model Context Protocol (MCP) server, it provides actions for connected integrations on Integration.app membrane as tools.

Here's our official AI Agent Example that shows you how to use this MCP server in your application.

📋 Prerequisites

• Node.js (v18 or higher)
• An Integration.app account

⚙️ Installation

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

🛠️ Local Development

To run the development server locally, start it with:

npm run dev

The server will be live at http://localhost:3000 ⚡️

🧪 Running tests

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

# then run tests
npm test

🚀 Deployment

Deploy your own instance of this MCP server to any cloud hosting service of your choice.

🐳 Docker

The project includes a Dockerfile for easy containerized deployment.

docker build -t integration-app-mcp-server .
docker run -p 3000:3000 integration-app-mcp-server

🔗 Connecting to the MCP server

This MCP server support two transports:

Transport	Endpoint	Status
SSE (Server‑Sent Events)	/sse	🔴 Deprecated — deprecated as of November 5, 2024 in MCP spec
HTTP (Streamable HTTP)	/mcp	🟢 Recommended — replaces SSE and supports bidirectional streaming

🔐 Authentication

Provide an Integration.app access token via query or Authorization header:

?token=ACCESS_TOKEN
Authorization: Bearer ACCESS_TOKEN

SSE (Deprecated)

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

Streamable HTTP (Recommended)

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

⚡ Static vs Dynamic Mode

By default, the MCP server runs in static mode, which means it returns all available tools (actions) for all connected integrations.

With dynamic mode (?mode=dynamic), the server will only return one tool: enable-tools. You can use this tool to selectively enable the tools you actually need for that session.

In dynamic mode, your implementation should figure out which tools are most relevant to the user's query. Once you've identified them, prompt the LLM to call the enable-tools tool with the appropriate list.

Want to see how this works in practice? Check out our AI Agent Example.

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

const client = new Client({
  name: 'example-integration-app-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'],
  },
});

🔧 Getting tools for a specific integrations

In static mode, the MCP server fetches tools from all active connections associated with the provided token.

You can choose to only fetch tools for a specific integration by passing the apps query parameter: /mcp?apps=google-calendar,google-docs

💬 Chat Session Management (Experimental)

The MCP server (streamable-http transport only) supports persistent chat sessions. Include an x-chat-id header in your requests to automatically track sessions for that specific chat. This is an experimental feature that we provide in addition to standard MCP sessions.

Starting a new chat session:

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

Retrieving your chat sessions:

GET /mcp/sessions
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

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

This feature lets you use same session for a conversation. Check out our AI Agent Example to see how this works in practice.

Configuring other MCP clients

📝 Cursor

To use this server with Cursor, update the ~/.cursor/mcp.json file:

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

Restart Cursor for the changes to take effect.

🤖 Claude Desktop

To use this server with Claude, update the config file (Settings > Developer > Edit Config):

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

🔧 Troubleshooting

• Ensure your access token is valid and you're generating it according to these instructions
• Check the MCP server logs for any errors or issues during startup or connection attempts.
• Use the MCP Inspector for testing and debugging