MCP Server

The MCP tab in ConnectIQ contains the documentation for the iMBrace MCP Server. The MCP Server uses the Model Context Protocol (MCP) to connect AI tools such as Claude Code, Cursor, Codex CLI and Claude Desktop directly to your iMBrace account. Once connected, your AI tool can work with your iMBrace data on your behalf. For example, it can:

• List your CRM boards.

• Read conversations.

• Check workflow runs.

Before you start

You need two things to connect an AI tool:

Requirement	Description
MCP server URL	The iMBrace gateway hosts the MCP server at the /mcp path. There is nothing to install or run yourself.
API key	An external token that your AI tool sends as a Bearer token. The AI tool can only access what your organization and user role allow.

Note: The examples in this guide use the sandbox gateway (https://app-gateway.sandbox.imbrace.co/mcp). Replace the host with the gateway for your environment.

Connecting an AI tool

Step 1: Generate an API key

1. Go to Settings → Generate External Token.

2. Generate a new external token.

3. Copy the key and store it securely. The key begins with api_.

For more information, see Getting an API Key.

Step 2: Add iMBrace to your AI tool

Select one of the AI tool below and add the configuration. In each example, replace api_xxx... with your API key.

1. Claude Code

Run the following command in your terminal:

claude mcp add --transport http imbrace "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

1. Cursor

Add the following .cursor/mcp.json to your project. To make iMBrace available in all projects, add ~/.cursor/mcp.json instead.

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

1. Codex CLI

For recent versions of Codex that support HTTP MCP servers, add the following ~/.codex/config.toml:

[mcp_servers.imbrace]
url = "https://app-gateway.sandbox.imbrace.co/mcp"
bearer_token = "api_xxx..."

For older versions of Codex without HTTP support, connect through mcp-remote instead:

[mcp_servers.imbrace]
command = "npx"
args = ["-y", "mcp-remote", "https://app-gateway.sandbox.imbrace.co/mcp", "--header", "Authorization: Bearer api_xxx..."]

1. Claude Desktop

Claude Desktop runs MCP servers locally, so it connects to iMBrace through mcp-remote.

1. In Claude Desktop, go to Settings → Developer → Edit Config.

2. Add the following claude_desktop_config.json

{
  "mcpServers": {
    "imbrace": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app-gateway.sandbox.imbrace.co/mcp",
        "--header", "Authorization: Bearer api_xxx..."
      ]
    }
  }
}

1. Other clients

Any MCP client that accepts a URL and headers can use the standard configuration:

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

If your client only supports local (stdio) servers, connect through mcp-remote:

npx -y mcp-remote "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

Step 3: Test the connection

Ask your AI tool a question such as:

• "List my iMBrace boards"

• "Show my latest conversations"

If the connection is working, the AI tool will use iMBrace tools such as listBoards, listConversations and listFlows to answer.

Controlling access

By default, the MCP Server is read-only. Your AI tool can view data but cannot create, change or delete anything. To allow more access or to limit the AI tool to specific areas, add query parameters to the MCP server URL in your configuration.

Parameter	Effect
?allowWrite=1	Allows the AI tool to create and update data.
?allowDestructive=1	Allows the AI tool to delete data. This also includes write access.
?services=dataBoard,workflow	Limits the AI tool to the listed services only.
?tags=boards,records	Limits the AI tool to the listed topics only.

Available services are dataBoard, channel, platform, marketplace and workflow. To combine parameters, join them with &. For example, to give an AI tool write access to data boards only, use:

https://app-gateway.sandbox.imbrace.co/mcp?services=dataBoard&allowWrite=1

Tip: Only enable write or delete access when needed. If the AI tool tries to use a tool that is not enabled, it receives a clear error message instead of failing silently.

How it works

Each request from your AI tool is sent through the iMBrace gateway's standard API routes using your API key. This means your organization's scoping, user permissions, and license checks apply exactly as they would if you called the API yourself.

The MCP Server uses the same set of agent tools that power the iMBrace SDK. It is a stateless service, so there are no sessions to manage.

Other ways to connect

OpenAPI

Some platforms, such as Open WebUI, use OpenAPI tool specifications instead of MCP. These platforms can connect to:

GET /agent-tools/openapi.json

Use the same Authorization header as the MCP configuration. This returns the agent tools from all services in a single specification, so you only need to add one tool server instead of five. You can use the same ?services= and ?tags= filters to limit what is included.

iMBrace CLI

If you prefer to run a local server using credentials from your CLI profile, the iMBrace CLI includes the same tools. Run:

imbrace mcp