MCP Gateway Setup

Connect one MCP server to all your cloud integrations through the Private or Business Gateway on stackgate.ai.

Overview

The Private Gateway and Business Gateway let you connect one MCP server to every active cloud integration on stackgate.ai, instead of adding a separate endpoint per service.

Gateway	Endpoint	Best for
Private Gateway	`POST /mcp/private`	Personal integrations on your account
Business Gateway	`POST /mcp/business`	Company workspaces with allowlists and environments

Device-bound integrations (Apple Notes, Aula) require the stackgate.ai desktop app — they are not available on cloud HTTP gateways.

When to use gateway vs dedicated endpoints

Dedicated endpoint (/mcp/trello, /mcp/gmail, …)

Least privilege: scope a token to one integration only
Smaller tool surface for the AI client
Good when you only need one service

Gateway (/mcp/private or /mcp/business)

One MCP config for all connected integrations
Namespaced tools like trello__list_boards and gmail__list_messages
Service discovery via list_services and describe_service
Good for multi-integration workflows and assistants that pick tools dynamically

Default to dedicated endpoints when you know exactly which integration you need. Use a gateway when you want one connection for your whole stack.

Prerequisites

A stackgate.ai account with at least one connected integration
An API token scoped to mcp:private-gateway and/or mcp:business-gateway (or a narrower server list)
An MCP client that supports HTTP transport (Cursor, Claude Desktop, Claude Code, Claude web, or raw HTTP)

Create tokens under API Tokens in the dashboard. For least privilege, select only the gateway server you need instead of leaving access empty (which grants full access).

Private Gateway

The private gateway exposes every enabled personal integration for your account over cloud HTTP.

Authentication

Send a Sanctum bearer token on every request:

Authorization: Bearer <your-api-token>
Accept: application/json, text/event-stream

Core gateway tools

When the Gateway Tool Cap is active (?max_tools= and enough eligible tools), tools/list exposes discovery and mutation-scoped dispatch tools:

Tool	Purpose
`list_services`	List connected integrations active for this gateway
`describe_service`	Inspect tools, mutations, schemas, and docs URLs for one integration slug
`query_data`	Call a read-only (`mutation=read`) integration tool
`create_data`	Call a create (`mutation=create`) integration tool
`update_data`	Call an update (`mutation=update`) integration tool
`delete_data`	Call a delete (`mutation=delete`) integration tool
`execute_data`	Deprecated catch-all dispatch (hidden when `actor=claude`)

Tool names use snake_case without a -tool suffix (for example list_boards, not list-boards-tool).

You can still call integration tools directly with namespaced names when uncapped or when you already know the name.

Namespaced tool names

Integration tools are also available as {integration}__{tool_name} on the gateway, for example:

trello__list_boards
gmail__list_messages
slack__list_channels

Use namespaced names when you already know the tool. Use describe_service when you need to discover available tools for a service.

Example workflow

Call list_services to see which integrations are active.
Call describe_service with service: trello to list Trello tools, mutations, and input schemas.
Call trello__list_boards directly, or use query_data / create_data / update_data / delete_data with service, tool, and arguments matching the tool mutation.

Business Gateway

The business gateway is for company workspaces. It respects:

Company integration allowlist — only integrations your company admin has enabled appear
Environments — tokens can be bound to a specific environment; MCP calls use that environment's credentials
Audit and usage attribution — tool calls are logged with company, environment, and token context

Company members still connect personal credentials for OAuth integrations; the gateway resolves the right credential for the active environment.

Create a token with mcp:business-gateway scope (or select business-gateway under MCP server access). Set an environment on the token when your company uses multiple environments.

Raw HTTP MCP clients

Point any HTTP MCP client at the gateway URL with bearer authentication. Example initialize request:

POST /mcp/private HTTP/1.1
Host: stackgate.ai
Authorization: Bearer <your-api-token>
Accept: application/json, text/event-stream
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}

Then call tools/list or invoke a namespaced tool with tools/call.

Local device-bound integrations

Apple Notes and Aula run on your Mac through the stackgate.ai desktop app. Download the app, sign in, connect the integration on the website, then use Configure Cursor or Configure Claude in the app menu. You do not need to run stackgate.ai locally or install PHP.

Troubleshooting

Problem	Likely cause	Fix
401 Unauthorized	Missing or invalid API token	Create a new token under API Tokens
403 Forbidden	Token not scoped to this gateway	Recreate token with `mcp:private-gateway` or `mcp:business-gateway`
Integration missing from gateway	Not connected or disabled	Connect under My Integrations and ensure it is enabled
Device-bound integration unavailable	Cloud gateway excludes local-only types	Use the desktop app for Apple Notes and Aula
Tool not found	Wrong namespaced name	Run `describe_service` for the correct tool slug

Related docs

All integrations — per-integration setup guides
Workflow playbooks — multi-integration recipes
API reference — endpoint list and authentication overview

Private Gateway — client config

Create an API token scoped to mcp:private-gateway, then add one of these HTTP configs to your MCP client.

{
    "mcpServers": {
        "private-gateway": {
            "url": "https://stackgate.ai/mcp/private?actor=cursor&max_tools=80"
        }
    }
}

This config already uses discovery tool mode to keep the tool list small and control token usage.

File: .cursor/mcp.json (project) or Cursor Settings → MCP

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config. Sign in via OAuth when your MCP client connects — no API token required in the config.

{
    "mcpServers": {
        "private-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/private?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/private?actor=cursor&max_tools=80

File: .mcp.json in your project root

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "mcpServers": {
        "private-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/private?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/private?actor=cursor&max_tools=80

File: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "name": "Private Gateway",
    "url": "https://stackgate.ai/mcp/private?actor=cursor"
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/private?actor=cursor&max_tools=80

Where: Claude → Customize → Connectors → Add (Add custom connector)

Claude Add custom connector dialog — paste the Remote MCP server URL — Paste the url value into the Remote MCP server URL field. Use the name for the connector name.

Connect integrations under My Integrations first. Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "name": "Private Gateway",
    "url": "https://stackgate.ai/mcp/private?actor=cursor"
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/private?actor=cursor&max_tools=80

Where: https://chatgpt.com/plugins → + (New Plugin)

ChatGPT New Plugin dialog — paste the Server URL — Choose Server URL, paste the url value, set Authentication to OAuth, then create the plugin.

Set Authentication to OAuth. Connect integrations under My Integrations first. Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "mcpServers": {
        "private-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/private?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/private?actor=cursor&max_tools=80

File: Same file as Claude Desktop — claude_desktop_config.json

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

Business Gateway — client config

For company workspaces. Create a token scoped to mcp:business-gateway and optionally bind an environment.

{
    "mcpServers": {
        "business-gateway": {
            "url": "https://stackgate.ai/mcp/business?actor=cursor&max_tools=80"
        }
    }
}

This config already uses discovery tool mode to keep the tool list small and control token usage.

File: .cursor/mcp.json (project) or Cursor Settings → MCP

{
    "mcpServers": {
        "business-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/business?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/business?actor=cursor&max_tools=80

File: .mcp.json in your project root

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "mcpServers": {
        "business-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/business?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/business?actor=cursor&max_tools=80

File: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "name": "Business Gateway",
    "url": "https://stackgate.ai/mcp/business?actor=cursor"
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/business?actor=cursor&max_tools=80

Where: Claude → Customize → Connectors → Add (Add custom connector)

Connect integrations under My Integrations first. Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.

{
    "name": "Business Gateway",
    "url": "https://stackgate.ai/mcp/business?actor=cursor"
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/business?actor=cursor&max_tools=80

Where: https://chatgpt.com/plugins → + (New Plugin)

{
    "mcpServers": {
        "business-gateway": {
            "type": "http",
            "url": "https://stackgate.ai/mcp/business?actor=cursor"
        }
    }
}

If you want to control token usage a bit more, use discovery tool mode: https://stackgate.ai/mcp/business?actor=cursor&max_tools=80

File: Same file as Claude Desktop — claude_desktop_config.json

Exposes all cloud-runnable active integrations. Device-bound services (Apple Notes, Aula) require the local gateway stdio config.